برنامج تشغيل Databricks JDBC (OSS)

يوفر Databricks برنامج تشغيل JDBC لبرنامج مصدر مفتوح (OSS) يمكنك من توصيل أدوات مثل DataGrip وDBeaver وSQL Workbench/J ب Azure Databricks من خلال اتصال قاعدة بيانات Java (JDBC)، وهي مواصفات قياسية في الصناعة للوصول إلى أنظمة إدارة قواعد البيانات.

قام برنامج التشغيل هذا بتنفيذ واجهات برمجة تطبيقات JDBC ويوفر وظائف أساسية بما في ذلك OAuth وجلب السحابة وميزات مثل استيعاب وحدة تخزين كتالوج Unity. يقوم بتشغيل وضع الاستعلام الأصلي ويدعم الاستعلام الأصلي ذات المعلمات، ويمكن تشغيله باستخدام واجهات برمجة تطبيقات تنفيذ العبارة، والتي توفر ميزة استبقاء نتائج الاستعلام المفيدة، أو Thrift.

توفر هذه المقالة معلومات حول تثبيت Databricks JDBC Driver (OSS) واستخدامه. للحصول على معلومات حول برنامج تشغيل Databricks JDBC غير OSS، راجع Databricks JDBC Driver.

المتطلبات

لاستخدام برنامج تشغيل Databricks JDBC (OSS)، يجب استيفاء المتطلبات التالية:

• Java Runtime Environment (JRE) 11.0 أو أعلى. يتم دعم اختبار CI على JRE 11 و17 و21.

تثبيت برنامج التشغيل

يتم نشر برنامج تشغيل Databricks JDBC (OSS) في مستودع Maven. أحدث إصدار هو 0.9.6-oss.

لتثبيت برنامج التشغيل، يمكنك القيام بأي مما يلي:

• بالنسبة لمشاريع Maven، أضف التبعية التالية إلى ملف المشروع pom.xml لإرشاد Maven لتنزيل برنامج تشغيل JDBC تلقائيا باستخدام الإصدار المحدد:

  <dependency>
    <groupId>com.databricks</groupId>
    <artifactId>databricks-jdbc</artifactId>
    <version>0.9.6-oss</version>
    <scope>runtime</scope>
  </dependency>
  

• بالنسبة لمشاريع Gradle، أضف التبعية التالية إلى ملف إنشاء المشروع لإرشاد Gradle لتنزيل برنامج تشغيل JDBC تلقائيا باستخدام الإصدار المحدد:

  implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
  

لعرض بناء جملة التبعية وأنواع المشاريع الأخرى، والحصول على أحدث رقم إصدار لبرنامج تشغيل Databricks JDBC (OSS)، راجع مستودع Maven.

تكوين عنوان URL للاتصال

للاتصال بمساحة عمل Azure Databricks باستخدام برنامج تشغيل JDBC، تحتاج إلى تحديد عنوان URL لاتصال JDBC يتضمن إعدادات اتصال مختلفة مثل اسم مضيف خادم مساحة عمل Azure Databricks وإعدادات مورد الحساب وبيانات اعتماد المصادقة للاتصال بمساحة العمل.

يمكنك تعيين قيمة هذه الخصائص على عنوان URL لاتصال JDBC، وتعيينها وتمريرها إلى أسلوب DriverManager.getConnection، أو مزيج من كليهما. راجع وثائق الموفر للحصول على أفضل طريقة للاتصال باستخدام تطبيق أو عميل أو SDK أو API أو أداة SQL معينة.

يجب أن يكون عنوان URL لاتصال JDBC بالتنسيق التالي. الخصائص غير حساسة لحالة الأحرف.

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

بدلا من ذلك، حدد الإعدادات باستخدام java.util.Properties الفئة أو مجموعة:

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

يتم وصف عناصر عنوان URL للاتصال في الجدول التالي. للحصول على معلومات حول خصائص إضافية، بما في ذلك خصائص المصادقة، راجع الأقسام أدناه. عناصر URL وخصائصه غير حساسة لحالة الأحرف.

للحصول على عنوان URL لاتصال JDBC لنظام مجموعة Azure Databricks:

1. سجل الدخول إلى مساحة عمل Azure Databricks.
2. في الشريط الجانبي، انقر فوق حساب، ثم انقر فوق اسم نظام المجموعة الهدف.
3. في علامة التبويب Configuration ، قم بتوسيع Advanced options.
4. انقر فوق علامة التبويب JDBC/ODBC.
5. انسخ عنوان URL ل JDBC لاستخدامه كعنول URL لاتصال JDBC، أو أنشئ عنوان URL من القيم الموجودة في حقول اسم مضيف الخادم والمنفذ ومسار HTTP.

للحصول على عنوان URL لاتصال JDBC لمستودع Databricks SQL:

1. سجل الدخول إلى مساحة عمل Azure Databricks.
2. في الشريط الجانبي، انقر فوق SQL Warehouses، ثم انقر فوق اسم المستودع الهدف.
3. انقر فوق علامة التبويب تفاصيل الاتصال.
4. انسخ عنوان URL ل JDBC لاستخدامه كعنول URL لاتصال JDBC، أو أنشئ عنوان URL من القيم الموجودة في حقول اسم مضيف الخادم والمنفذ ومسار HTTP.

مصادقة برنامج التشغيل

يمكنك مصادقة اتصال برنامج تشغيل JDBC باستخدام إحدى آليات المصادقة التالية:

• مصادقة OAuth من مستخدم إلى جهاز (U2M) (مستحسن)
• مصادقة OAuth من جهاز إلى جهاز (M2M)
• الرمز المميز للوصول الشخصي ل Azure Databricks

مصادقة OAuth من مستخدم إلى جهاز (U2M)

يدعم برنامج تشغيل JDBC مصادقة OAuth من مستخدم إلى جهاز (U2M) لتسجيل الدخول البشري في الوقت الحقيقي والموافقة على مصادقة حساب مستخدم Databricks الهدف. يعرف هذا أيضا باسم مصادقة OAuth المستندة إلى المستعرض.

أنشأت Azure Databricks معرف databricks-sql-jdbc عميل OAuth للعملاء. هذا هو أيضا معرف عميل OAuth الافتراضي المستخدم في برنامج تشغيل JDBC. لتكوين مصادقة OAuth U2M، ما عليك سوى إضافة الخصائص التالية إلى عنوان URL أو java.util.Properties الكائن الحالي لاتصال JDBC:

مصادقة OAuth من جهاز إلى جهاز (M2M)

يدعم برنامج تشغيل JDBC مصادقة OAuth من جهاز إلى جهاز (M2M) باستخدام كيان خدمة Azure Databricks. يعرف هذا أيضا باسم مصادقة بيانات اعتماد عميل OAuth 2.0. راجع مصادقة الوصول إلى Azure Databricks باستخدام كيان خدمة باستخدام OAuth (OAuth M2M).

لتكوين مصادقة بيانات اعتماد عميل OAuth M2M أو OAuth 2.0:

1. إنشاء كيان خدمة مدار من Microsoft Entra ID ثم تعيينه إلى حسابات Azure Databricks ومساحات العمل. للحصول على التفاصيل، راجع إدارة كيانات الخدمة.

   هام

   يدعم برنامج تشغيل Databricks JDBC (OSS) أسرار Azure Databricks OAuth لمصادقة بيانات اعتماد عميل OAuth M2M أو OAuth 2.0. أسرار معرف Microsoft Entra غير مدعومة.

2. إنشاء سر Azure Databricks OAuth لمدير الخدمة. للقيام بذلك، راجع إنشاء رموز الوصول المميزة واستخدامها يدويا لمصادقة OAuth M2M.

3. امنح كيان الخدمة حق الوصول إلى نظام المجموعة أو المستودع. راجع حساب الأذونات أو إدارة مستودع SQL.

أضف الخصائص التالية إلى عنوان URL أو java.util.Properties كائن اتصال JDBC الموجود لديك:

الرمز المميز للوصول الشخصي ل Azure Databricks

لمصادقة اتصال برنامج تشغيل JDBC باستخدام رمز مميز للوصول الشخصي ل Azure Databricks، أضف الخصائص التالية إلى عنوان URL أو java.util.Properties كائن اتصال JDBC:

خصائص الاتصال

يتم دعم خصائص الاتصال الإضافية التالية بواسطة برنامج تشغيل JDBC. الخصائص غير حساسة لحالة الأحرف.

خصائص تكوين SQL

يتم دعم خصائص تكوين SQL التالية بواسطة برنامج تشغيل JDBC. يتم وصفها أيضا في معلمات التكوين. الخصائص غير حساسة لحالة الأحرف.

تسجيل الخصائص

يتم دعم خصائص التسجيل التالية بواسطة برنامج تشغيل JDBC. الخصائص غير حساسة لحالة الأحرف.

تمكين التسجيل وتكوينه

يدعم برنامج تشغيل JDBC إطارات عمل Simple Logging Facade ل Java (SLF4J) وjava.util.logging (JUL ). يستخدم برنامج التشغيل إطار عمل تسجيل JUL بشكل افتراضي.

لتمكين التسجيل وتكوينه لبرنامج تشغيل JDBC:

1. تمكين إطار عمل التسجيل الذي تريد استخدامه:

   • لتسجيل SLF4J، قم بتعيين خاصية -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER النظام وتوفير تنفيذ ربط SLF4J (متوافق مع إصدار SLF4J 2.0.13 وما فوق) وملف التكوين المقابل في classpath.
   • لتسجيل JUL، قم بتعيين خاصية -Dcom.databricks.jdbc.loggerImpl=JDKLOGGERالنظام . هذا هو الوضع الافتراضي.

2. قم بتعيين الخاصية LogLevel على سلسلة الاتصال إلى المستوى المطلوب من المعلومات لتضمينها في ملفات السجل.

3. قم بتعيين الخاصية LogPath على سلسلة الاتصال إلى المسار الكامل إلى المجلد حيث تريد حفظ ملفات السجل.

   على سبيل المثال، يتيح عنوان URL للاتصال التالي مستوى التسجيل 6 ويحفظ ملفات السجل في المجلد C:temp:

   jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
   

4. أعد تشغيل تطبيق JDBC وأعد الاتصال بالخادم لتطبيق الإعدادات.

مثال: تشغيل استعلام باستخدام برنامج تشغيل JDBC

يوضح المثال التالي كيفية استخدام برنامج تشغيل JDBC لتشغيل استعلام Databricks SQL باستخدام مورد حساب Azure Databricks.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class DatabricksJDBCExample {

    public static void main(String[] args) {

        Class.forName("com.databricks.client.jdbc.Driver");

        // Set JDBC URL properties
        String jdbcUrl = "jdbc:databricks://dbc-a1b2345c-d6e7.cloud.databricks.com:443";
        Properties connectionProperties = new Properties();
        connectionProperties.put("httpPath", "sql/protocolv1/o/123456780012345/0123-123450-z000pi22");
        connectionProperties.put("ssl", "1");

        // Set authentication properties (personal access token)
        connectionProperties.put("AuthMech", "3");
        connectionProperties.put("user", "token");
        connectionProperties.put("password", "12345678901234667890abcdabcd");

        // Set logging properties
        connectionProperties.put("logPath", "logs/myapplication.log");

        // Establish connection and execute query
        try (Connection connection = DriverManager.getConnection(jdbcUrl, connectionProperties);
             Statement statement = connection.createStatement();
             ResultSet resultSet = statement.executeQuery("SELECT * FROM samples.nyctaxi.trips")) {

            // Get metadata and column names
            ResultSetMetaData metaData = resultSet.getMetaData();
            String[] columns = new String[metaData.getColumnCount()];
            for (int i = 0; i < columns.length; i++) {
                columns[i] = metaData.getColumnName(i + 1);
            }

            // Process and print the result set
            while (resultSet.next()) {
                System.out.print("Row " + resultSet.getRow() + "=[");
                for (int i = 0; i < columns.length; i++) {
                    if (i != 0) {
                        System.out.print(", ");
                    }
                    System.out.print(columns[i] + "='" + resultSet.getObject(i + 1) + "'");
                }
                System.out.println("]");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

الموارد الإضافية

• تكامل DataGrip مع Azure Databricks

• تكامل DBeaver مع Azure Databricks

• الاتصال ب SQL Workbench/J

• الاتصال ب Infoworks

• الاتصال ب Qlik Replicate

• الاتصال ب StreamSets

• الاتصال ب Syncsort

• الاتصال ب MicroStrategy