تثبيت Databricks Connect ل Python

إشعار

تتناول هذه المقالة Databricks Connect ل Databricks Runtime 13.3 LTS وما فوق.

توضح هذه المقالة كيفية تثبيت Databricks Connect ل Python. راجع ما هو Databricks Connect؟. للحصول على إصدار Scala من هذه المقالة، راجع تثبيت Databricks Connect ل Scala.

المتطلبات

لتثبيت Databricks Connect ل Python، يجب استيفاء المتطلبات التالية:

• إذا كنت تتصل بحساب بلا خادم، يجب أن تفي مساحة العمل بمتطلبات الحوسبة بلا خادم.

  إشعار

  يتم دعم الحوسبة بلا خادم في Databricks Connect الإصدار 15.1 والإصدارات الأحدث. بالإضافة إلى ذلك، فإن إصدارات Databricks Connect في إصدار وقت تشغيل Databricks أو أقل منه على بلا خادم متوافقة تماما. راجع ملاحظات الإصدار. للتحقق مما إذا كان إصدار Databricks Connect متوافقا مع الحوسبة بلا خادم، راجع التحقق من صحة الاتصال ب Databricks.

• إذا كنت تتصل بمجموعة، يجب أن تفي المجموعة المستهدفة بمتطلبات تكوين نظام المجموعة، والتي تتضمن متطلبات إصدار Databricks Runtime.

• يجب أن يكون لديك Python 3 مثبتا على جهاز التطوير الخاص بك، ويجب أن يفي الإصدار الثانوي من Python المثبت على جهاز التطوير بمتطلبات الإصدار في الجدول أدناه.

  نوع الحساب	إصدار Databricks Connect	إصدار Python متوافق
  دون خادم	15.1 وما فوق	3.11
  نظام المجموعة	15.1 وما فوق	3.11
  نظام المجموعة	13.3 LTS إلى 14.3 LTS	3.10

• إذا كنت ترغب في استخدام PySpark UDFs، يجب أن يتطابق الإصدار الثانوي المثبت لجهاز التطوير الخاص بك من Python مع الإصدار الثانوي من Python المضمن مع Databricks Runtime المثبت على نظام المجموعة أو الحوسبة بلا خادم. للعثور على إصدار Python الثانوي من مجموعتك، راجع قسم بيئة النظام في ملاحظات إصدار Databricks Runtime لنظام المجموعة أو الحوسبة بلا خادم. راجع إصدارات ملاحظات إصدار Databricks Runtime والتوافق وملاحظات إصدار الحساب بلا خادم.

تنشيط بيئة Python الظاهرية

توصي Databricks بشدة بتنشيط بيئة Python الظاهرية لكل إصدار Python تستخدمه مع Databricks Connect. تساعد بيئات Python الظاهرية على التأكد من أنك تستخدم الإصدارات الصحيحة من Python وDatabricks Connect معا. لمزيد من المعلومات حول هذه الأدوات وكيفية تنشيطها، راجع venv أو الشعر.

تثبيت عميل Databricks Connect

يصف هذا القسم كيفية تثبيت عميل Databricks Connect مع venv أو الشعر.

إشعار

إذا كان لديك بالفعل ملحق Databricks ل Visual Studio Code مثبتا، فلن تحتاج إلى اتباع إرشادات الإعداد هذه، لأن ملحق Databricks ل Visual Studio Code يحتوي بالفعل على دعم مضمن ل Databricks Connect ل Databricks Runtime 13.3 LTS وما فوق. انتقل إلى Debug code باستخدام Databricks Connect لملحق Databricks ل Visual Studio Code.

تثبيت عميل Databricks Connect مع venv

1. مع تنشيط بيئتك الظاهرية، قم بإلغاء تثبيت PySpark، إذا كان مثبتا بالفعل، عن طريق تشغيل uninstall الأمر . هذا مطلوب لأن الحزمة databricks-connect تتعارض مع PySpark. للحصول على التفاصيل، راجع عمليات تثبيت PySpark المتعارضة. للتحقق مما إذا كان PySpark مثبتا بالفعل، قم بتشغيل show الأمر .

   # Is PySpark already installed?
   pip3 show pyspark
   
   # Uninstall PySpark
   pip3 uninstall pyspark
   

2. مع استمرار تنشيط بيئتك الظاهرية، قم بتثبيت عميل Databricks Connect عن طريق تشغيل install الأمر . --upgrade استخدم الخيار لترقية أي تثبيت عميل موجود إلى الإصدار المحدد.

   pip3 install --upgrade "databricks-connect==15.4.*"  # Or X.Y.* to match your cluster version.
   

   إشعار

   توصي Databricks بإلحاق رمز "dot-asterisk" لتحديد databricks-connect==X.Y.* بدلا من databricks-connect=X.Y، للتأكد من تثبيت أحدث حزمة. على الرغم من أن هذا ليس مطلبا، فإنه يساعد على التأكد من أنه يمكنك استخدام أحدث الميزات المدعومة لتلك المجموعة.

انتقل إلى تكوين خصائص الاتصال.

تثبيت عميل Databricks Connect مع الشعر

1. مع تنشيط بيئتك الظاهرية، قم بإلغاء تثبيت PySpark، إذا كان مثبتا بالفعل، عن طريق تشغيل remove الأمر . هذا مطلوب لأن الحزمة databricks-connect تتعارض مع PySpark. للحصول على التفاصيل، راجع عمليات تثبيت PySpark المتعارضة. للتحقق مما إذا كان PySpark مثبتا بالفعل، قم بتشغيل show الأمر .

   # Is PySpark already installed?
   poetry show pyspark
   
   # Uninstall PySpark
   poetry remove pyspark
   

2. مع استمرار تنشيط بيئتك الظاهرية، قم بتثبيت عميل Databricks Connect عن طريق تشغيل add الأمر .

   poetry add databricks-connect@~15.4  # Or X.Y to match your cluster version.
   

   إشعار

   توصي Databricks باستخدام علامة "at-tilde" لتحديد databricks-connect@~15.4 بدلا من databricks-connect==15.4، للتأكد من تثبيت أحدث حزمة. على الرغم من أن هذا ليس مطلبا، فإنه يساعد على التأكد من أنه يمكنك استخدام أحدث الميزات المدعومة لتلك المجموعة.

تكوين خصائص الاتصال

في هذا القسم، يمكنك تكوين خصائص لإنشاء اتصال بين Databricks Connect والمجموعة Azure Databricks أو الحوسبة بلا خادم، والتي تتضمن ما يلي:

• اسم مثيل مساحة عمل Azure Databricks. هذه هي قيمة Server Hostname للحساب الخاص بك. راجع الحصول على تفاصيل الاتصال لمورد حساب Azure Databricks.
• أي خصائص أخرى ضرورية لنوع مصادقة Databricks التي تريد استخدامها.

إشعار

• يتم دعم مصادقة OAuth من مستخدم إلى جهاز (U2M) على Databricks SDK ل Python 0.19.0 وما فوق. قد تحتاج إلى تحديث الإصدار المثبت لمشروع التعليمات البرمجية الخاص بك من Databricks SDK ل Python إلى 0.19.0 أو أعلى لاستخدام مصادقة OAuth U2M. راجع بدء استخدام Databricks SDK ل Python.

  بالنسبة لمصادقة OAuth U2M، يجب استخدام Databricks CLI للمصادقة قبل تشغيل تعليمة Python البرمجية الخاصة بك. راجع البرنامج التعليمي.

• يتم دعم مصادقة OAuth من جهاز إلى جهاز (M2M) لمصادقة OAuth من جهاز إلى جهاز (M2M) على Databricks SDK ل Python 0.18.0 وما فوق. قد تحتاج إلى تحديث الإصدار المثبت لمشروع التعليمات البرمجية الخاص بك من Databricks SDK ل Python إلى 0.18.0 أو أعلى لاستخدام مصادقة OAuth M2M. راجع بدء استخدام Databricks SDK ل Python.

• لم تقم Databricks SDK ل Python بعد بتنفيذ مصادقة الهويات المدارة من Azure.

تكوين اتصال بمجموعة

لتكوين اتصال بمجموعة، ستحتاج إلى معرف نظام المجموعة الخاص بك. يمكنك الحصول على معرف نظام المجموعة من عنوان URL. راجع عنوان URL للمجموعة والمعرف.

يمكنك تكوين الاتصال بالمجموعة بإحدى الطرق التالية. يبحث Databricks Connect عن خصائص التكوين بالترتيب التالي، ويستخدم التكوين الأول الذي يعثر عليه. للحصول على معلومات التكوين المتقدمة، راجع الاستخدام المتقدم ل Databricks Connect ل Python.

1. أسلوب remote() لفئة DatabricksSession.
2. ملف تعريف تكوين Databricks
3. متغير البيئة DATABRICKS_CONFIG_PROFILE
4. متغير بيئة لكل خاصية تكوين
5. ملف تعريف تكوين Databricks يسمى DEFAULT

DatabricksSession أسلوب الفئة remote()

بالنسبة لهذا الخيار، الذي ينطبق على مصادقة رمز الوصول الشخصي Azure Databricks فقط، حدد اسم مثيل مساحة العمل، ورمز الوصول الشخصي Azure Databricks، ومعرف نظام المجموعة.

يمكنك تهيئة الفئة بعدة DatabricksSession طرق، كما يلي:

• hosttokenقم بتعيين الحقول و و cluster_id في DatabricksSession.builder.remote().
• استخدم فئة Databricks SDK Config .
• حدد ملف تعريف تكوين Databricks مع cluster_id الحقل.
• تعيين سلسلة الاتصال Spark Connect في DatabricksSession.builder.remote().

بدلا من تحديد خصائص الاتصال هذه في التعليمات البرمجية الخاصة بك، توصي Databricks بتكوين الخصائص من خلال متغيرات البيئة أو ملفات التكوين، كما هو موضح في هذا القسم. تفترض أمثلة التعليمات البرمجية التالية أنك توفر بعض التنفيذ للوظائف المقترحة retrieve_* للحصول على الخصائص الضرورية من المستخدم أو من مخزن تكوين آخر، مثل Azure KeyVault.

التعليمات البرمجية لكل من هذه الأساليب كما يلي:

# Set the host, token, and cluster_id fields in DatabricksSession.builder.remote.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.remote(
   host       = f"https://{retrieve_workspace_instance_name()}",
   token      = retrieve_token(),
   cluster_id = retrieve_cluster_id()
).getOrCreate()

# Use the Databricks SDK's Config class.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   host       = f"https://{retrieve_workspace_instance_name()}",
   token      = retrieve_token(),
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Specify a Databricks configuration profile along with the `cluster_id` field.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   profile    = "<profile-name>",
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

ملف تعريف تكوين Databricks

لهذا الخيار، قم بإنشاء أو تعريف ملف تعريف تكوين Azure Databricks يحتوي على الحقل cluster_id وأي حقول أخرى ضرورية لنوع مصادقة Databricks الذي تريد استخدامه.

حقول ملف تعريف التكوين المطلوبة لكل نوع مصادقة هي كما يلي:

• لمصادقة الرمز المميز للوصول الشخصي إلى Azure Databricks: host وtoken.
• لمصادقة OAuth من جهاز إلى جهاز (M2M) (حيثما كان مدعوما): hostو client_idو.client_secret
• لمصادقة OAuth من مستخدم إلى جهاز (U2M) (حيثما كان مدعوما): host.
• بالنسبة إلى Microsoft Entra ID (المعروف سابقا ب Azure Active Directory) المصادقة الأساسية للخدمة: hostو azure_client_secretazure_tenant_idazure_client_idوربما .azure_workspace_resource_id
• لمصادقة Azure CLI: host.
• بالنسبة إلى مصادقة الهويات المدارة من Azure (حيثما كان مدعوما): host، azure_use_msiazure_client_idوربما azure_workspace_resource_id.

ثم قم بتعيين اسم ملف تعريف التكوين هذا من خلال Config الفئة .

يمكنك تحديد cluster_id بعدة طرق، كما يلي:

• قم بتضمين cluster_id الحقل في ملف تعريف التكوين الخاص بك، ثم حدد اسم ملف تعريف التكوين فقط.
• حدد اسم ملف تعريف التكوين مع cluster_id الحقل.

إذا قمت بالفعل بتعيين DATABRICKS_CLUSTER_ID متغير البيئة مع معرف نظام المجموعة، فلن تحتاج أيضا إلى تحديد cluster_id.

التعليمات البرمجية لكل من هذه الأساليب كما يلي:

# Include the cluster_id field in your configuration profile, and then
# just specify the configuration profile's name:
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()

# Specify the configuration profile name along with the cluster_id field.
# In this example, retrieve_cluster_id() assumes some custom implementation that
# you provide to get the cluster ID from the user or from some other
# configuration store:
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   profile    = "<profile-name>",
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

DATABRICKS_CONFIG_PROFILE متغير البيئة

لهذا الخيار، قم بإنشاء أو تعريف ملف تعريف تكوين Azure Databricks يحتوي على الحقل cluster_id وأي حقول أخرى ضرورية لنوع مصادقة Databricks الذي تريد استخدامه.

إذا قمت بالفعل بتعيين DATABRICKS_CLUSTER_ID متغير البيئة مع معرف نظام المجموعة، فلن تحتاج أيضا إلى تحديد cluster_id.

حقول ملف تعريف التكوين المطلوبة لكل نوع مصادقة هي كما يلي:

• لمصادقة الرمز المميز للوصول الشخصي إلى Azure Databricks: host وtoken.
• لمصادقة OAuth من جهاز إلى جهاز (M2M) (حيثما كان مدعوما): hostو client_idو.client_secret
• لمصادقة OAuth من مستخدم إلى جهاز (U2M) (حيثما كان مدعوما): host.
• بالنسبة إلى Microsoft Entra ID (المعروف سابقا ب Azure Active Directory) المصادقة الأساسية للخدمة: hostو azure_client_secretazure_tenant_idazure_client_idوربما .azure_workspace_resource_id
• لمصادقة Azure CLI: host.
• بالنسبة إلى مصادقة الهويات المدارة من Azure (حيثما كان مدعوما): host، azure_use_msiazure_client_idوربما azure_workspace_resource_id.

DATABRICKS_CONFIG_PROFILE تعيين متغير البيئة إلى اسم ملف تعريف التكوين هذا. ثم قم بتهيئة DatabricksSession الفئة كما يلي:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

متغير بيئة لكل خاصية تكوين

لهذا الخيار، قم بتعيين DATABRICKS_CLUSTER_ID متغير البيئة وأي متغيرات بيئة أخرى ضرورية لنوع مصادقة Databricks الذي تريد استخدامه.

متغيرات البيئة المطلوبة لكل نوع مصادقة هي كما يلي:

• لمصادقة الرمز المميز للوصول الشخصي إلى Azure Databricks: DATABRICKS_HOST وDATABRICKS_TOKEN.
• لمصادقة OAuth من جهاز إلى جهاز (M2M) (حيثما كان مدعوما): DATABRICKS_HOSTو DATABRICKS_CLIENT_IDو.DATABRICKS_CLIENT_SECRET
• لمصادقة OAuth من مستخدم إلى جهاز (U2M) (حيثما كان مدعوما): DATABRICKS_HOST.
• بالنسبة إلى Microsoft Entra ID (المعروف سابقا ب Azure Active Directory) المصادقة الأساسية للخدمة: DATABRICKS_HOSTو ARM_CLIENT_SECRETARM_TENANT_IDARM_CLIENT_IDوربما .DATABRICKS_AZURE_RESOURCE_ID
• لمصادقة Azure CLI: DATABRICKS_HOST.
• بالنسبة إلى مصادقة الهويات المدارة من Azure (حيثما كان مدعوما): DATABRICKS_HOST، ARM_USE_MSIARM_CLIENT_IDوربما DATABRICKS_AZURE_RESOURCE_ID.

ثم قم بتهيئة DatabricksSession الفئة كما يلي:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

ملف تعريف تكوين Databricks المسمى DEFAULT

لهذا الخيار، قم بإنشاء أو تعريف ملف تعريف تكوين Azure Databricks يحتوي على الحقل cluster_id وأي حقول أخرى ضرورية لنوع مصادقة Databricks الذي تريد استخدامه.

إذا قمت بالفعل بتعيين DATABRICKS_CLUSTER_ID متغير البيئة مع معرف نظام المجموعة، فلن تحتاج أيضا إلى تحديد cluster_id.

حقول ملف تعريف التكوين المطلوبة لكل نوع مصادقة هي كما يلي:

• لمصادقة الرمز المميز للوصول الشخصي إلى Azure Databricks: host وtoken.
• لمصادقة OAuth من جهاز إلى جهاز (M2M) (حيثما كان مدعوما): hostو client_idو.client_secret
• لمصادقة OAuth من مستخدم إلى جهاز (U2M) (حيثما كان مدعوما): host.
• بالنسبة إلى Microsoft Entra ID (المعروف سابقا ب Azure Active Directory) المصادقة الأساسية للخدمة: hostو azure_client_secretazure_tenant_idazure_client_idوربما .azure_workspace_resource_id
• لمصادقة Azure CLI: host.
• بالنسبة إلى مصادقة الهويات المدارة من Azure (حيثما كان مدعوما): host، azure_use_msiazure_client_idوربما azure_workspace_resource_id.

قم بتسمية ملف تعريف DEFAULTالتكوين هذا .

ثم قم بتهيئة DatabricksSession الفئة كما يلي:

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

تكوين اتصال بالحوسبة بلا خادم

هام

هذه الميزة في المعاينة العامة.

يدعم Databricks Connect الاتصال بالحوسبة بلا خادم. لاستخدام هذه الميزة، يجب استيفاء متطلبات الاتصال بلا خادم. راجع المتطلبات.

هام

تحتوي هذه الميزة على القيود التالية:

• جميع قيود Databricks Connect ل Python
• جميع قيود الحوسبة بلا خادم
• يمكن استخدام تبعيات Python المضمنة كجزء من بيئة الحوسبة بلا خادم فقط ل UDFs. راجع بيئة النظام. لا يمكن تثبيت تبعيات إضافية.
• UDFs مع وحدات مخصصة غير مدعومة.

يمكنك تكوين اتصال بالحوسبة بلا خادم بإحدى الطرق التالية:

• تعيين متغير DATABRICKS_SERVERLESS_COMPUTE_ID البيئة المحلية إلى auto. إذا تم تعيين متغير البيئة هذا، يتجاهل cluster_idDatabricks Connect .

• في ملف تعريف تكوين Databricks محلي، قم بتعيين serverless_compute_id = auto، ثم قم بالإشارة إلى ملف التعريف هذا من التعليمات البرمجية ل Databricks Connect Python.

  [DEFAULT]
  host = https://my-workspace.cloud.databricks.com/
  serverless_compute_id = auto
  token = dapi123...
  

• بدلا من ذلك، ما عليك سوى تحديث تعليمة Databricks Connect Python البرمجية كما يلي:

  from databricks.connect import DatabricksSession as SparkSession
  
  spark = DatabricksSession.builder.serverless(True).getOrCreate()
  

  from databricks.connect import DatabricksSession as SparkSession
  
  spark DatabricksSession.builder.remote(serverless=True).getOrCreate()
  

إشعار

مهلة جلسة الحساب بلا خادم بعد 10 دقائق من عدم النشاط. بعد ذلك، يجب إنشاء جلسة Spark جديدة للاتصال بالحوسبة بلا خادم. يمكن القيام بذلك باستخدام spark = DatabricksSession.builder.serverless(True).getOrCreate().

التحقق من صحة الاتصال ب Databricks

للتحقق من صحة البيئة الخاصة بك، يتم إعداد بيانات الاعتماد الافتراضية والاتصال بالحوسبة بشكل صحيح ل Databricks Connect، قم بتشغيل databricks-connect test الأمر الذي يفشل مع رمز خروج غير صفري ورسالة خطأ مقابلة عندما يكتشف أي عدم توافق في الإعداد.

databricks-connect test

يمكنك أيضا التحقق من صحة بيئتك في التعليمات البرمجية ل Python باستخدام validateSession():

DatabricksSession.builder.validateSession(True).getOrCreate()