مشاركة عبر

ترحيل Databricks CLI

  • مقالة

توضح هذه المقالة كيفية الترحيل من Databricks CLI الإصدار 0.18 أو أدناه إلى Databricks CLI الإصدار 0.205 أو أعلى. توجد إصدارات Databricks CLI 0.205 والإصدارات الأحدث في المعاينة العامة.

للإيجاز، تشير هذه المقالة إلى إصدارات Databricks CLI 0.18 والإصدارات أدناه باسم CLI "القديم"، وإصدارات Databricks CLI 0.205 وما فوق كواجهة سطر الأوامر "الجديدة".

لمزيد من المعلومات حول واجهات CLIs القديمة والجديدة، راجع:

إلغاء تثبيت CLI القديم

إذا كان لديك CLI القديم مثبتا وتريد إلغاء تثبيته، فاستخدم pip (أو pip3، اعتمادا على إصدار Python) لتشغيل uninstall الأمر، كما يلي:

pip uninstall databricks-cli

تثبيت CLI الجديد

لمعرفة كيفية تثبيت CLI الجديد، راجع تثبيت Databricks CLI أو تحديثه.

تحقق من تثبيت CLI الخاص بك

إذا لم تكن متأكدا مما إذا كنت تستخدم CLI الجديد، فاتبع الإرشادات الواردة في هذا القسم للتحقق والضبط حسب الحاجة. قبل اتباع هذه الإرشادات، تأكد من الخروج من أي بيئات أو بيئات conda أو بيئات Python ظاهرية أو بيئات مشابهة.

للتحقق من إصدار التثبيت الافتراضي ل CLI، قم بتشغيل الأمر التالي:

databricks -v

إذا لم يكن رقم الإصدار كما تتوقع، فقم بأحد الإجراءات التالية:

  • إذا كنت تريد استخدام إصدار واحد فقط من CLI: قم بإلغاء تثبيت جميع الإصدارات السابقة من CLI التي لم تعد تريد استخدامها. قد تحتاج إلى تحديث نظام PATH التشغيل بحيث يتم سرد المسار إلى الإصدار المتبقي من CLI الذي تريد استخدامه.
  • إذا كنت ترغب في الاستمرار في استخدام إصدارات متعددة من CLI: قم بإيقاف المسار الكامل إلى إصدار CLI الذي تريد استخدامه لكل استدعاء إلى CLI.
  • إذا كنت تريد الاستمرار في استخدام إصدارات متعددة من CLI، ولكنك لا تريد الاحتفاظ بإلحاق المسار الكامل إلى إصدار CLI الذي تستخدمه في معظم الأحيان: تأكد من إدراج المسار الكامل لهذا الإصدار أولا في نظام PATHالتشغيل الخاص بك. لاحظ أنه لا يزال يتعين عليك إلحاق المسار الكامل بإصدارات CLI غير المدرجة أولا في نظام PATHالتشغيل الخاص بك.

لتحديث نظام PATHالتشغيل الخاص بك، قم بما يلي:

MacOS أو Linux

  1. سرد المسارات التي databricks تم تثبيتها عن طريق تشغيل أحد الأوامر التالية:

    which -a databricks

# Or:
where databricks

  2. احصل على المسار إلى التثبيت الذي تريد استخدامه دون إلحاق المسار الكامل لكل استدعاء إلى CLI. إذا لم تكن متأكدا من المسار هذا، فقم بتشغيل المسار الكامل إلى كل موقع، متبوعا ب -v، على سبيل المثال:

    /usr/local/bin/databricks -v

  3. لوضع المسار إلى التثبيت الذي تريد استخدامه أولا في PATH، قم بتشغيل الأمر التالي، واستبدل /usr/local/bin بالمسار الذي تريد استخدامه. لا تقم بإضافة databricks إلى نهاية هذا المسار. على سبيل المثال:

    export PATH="/usr/local/bin:$PATH"

  4. للتحقق من تعيين PATH بشكل صحيح لجلسة المحطة الطرفية الحالية، قم بتشغيل databricks متبوعا ب -v وتحقق من رقم الإصدار:

    databricks -v

  5. لتعيين هذه الطريقة في PATH كل مرة تقوم فيها بإعادة تشغيل المحطة الطرفية، أضف الأمر من الخطوة 3 إلى ملف تهيئة shell. على سبيل المثال، بالنسبة إلى Zshell، يقع هذا الملف عادة في ~/.zshrc. بالنسبة إلى Bash، يقع هذا الملف عادة في ~/.bashrc. للحصول على shells الأخرى، راجع وثائق موفر shell.

  6. بعد تحديث ملف تهيئة shell، يجب إعادة تشغيل المحطة الطرفية لتطبيق القيمة المحدثة PATH .

Windows

  1. انقر بزر الماوس الأيمن فوق تثبيت databricks الذي تريد استخدامه دون إلحاق المسار الكامل لكل استدعاء إلى CLI.

  2. انقر فوق فتح موقع الملف.

  3. لاحظ المسار إلى databricks، على سبيل المثال C:\Windows.

  4. في قائمة البدء، ابحث عن متغيرات البيئة.

  5. انقر فوق تحرير متغيرات البيئة لحسابك.

  6. حدد متغير المسار في قسم User variables for<username>.

  7. انقر فوق تحرير.

  8. انقر فوق جديد.

  9. أدخل المسار الذي تريد إضافته، بدون databricks.exe (مثل C:\Windows).

  10. استخدم الزر نقل لأعلى لنقل المسار الذي أضفته للتو إلى بداية القائمة.

  11. وانقر فوق موافق.

  12. للتحقق من تعيين PATH بشكل صحيح، افتح موجه أوامر جديد، وقم بتشغيل databricks متبوعا ب -v، وتحقق من رقم الإصدار:

    databricks -v

استخدام أنواع مصادقة إضافية

يدعم كل من CLI القديم وCLI الجديد مصادقة رمز الوصول الشخصي Azure Databricks. ومع ذلك، توصي Databricks باستخدام أنواع مصادقة Azure Databricks الأخرى إذا كان ذلك ممكنا، والتي يدعمها CLI الجديد فقط.

إذا كان يجب عليك استخدام مصادقة الرمز المميز للوصول الشخصي ل Azure Databricks، توصي Databricks باستخدام مصادقة مقترنة بكيان خدمة بدلا من حساب Azure Databricks أو مستخدم مساحة العمل. راجع إدارة كيانات الخدمة.

يدعم CLI الجديد الرموز المميزة لمعرف Microsoft Entra بالإضافة إلى رموز الوصول الشخصية ل Azure Databricks. هذه الرموز المميزة الإضافية أكثر أمانا لأنها تنتهي صلاحيتها عادة في ساعة واحدة، بينما يمكن أن تكون رموز الوصول الشخصي Azure Databricks صالحة من يوم واحد إلى أجل غير مسمى. هذا مهم بشكل خاص إذا تم إيداع رمز مميز عن طريق الخطأ في أنظمة التحكم في الإصدار التي يمكن الوصول إليها من قبل الآخرين. أيضا، يمكن ل CLI الجديد تحديث هذه الرموز الإضافية تلقائيا عند انتهاء صلاحيتها، في حين أن تحديث الرموز المميزة للوصول الشخصي Azure Databricks إما عملية يدوية أو قد يكون من الصعب أتمتتها.

لمزيد من المعلومات، راجع المصادقة ل Databricks CLI.

مجموعة الأوامر ومقارنات الأوامر

يسرد الجدول التالي مجموعات أوامر CLI القديمة ومكافئات مجموعة أوامر CLI الجديدة. حيث توجد اختلافات كبيرة بين CLIs، تسرد الجداول الإضافية أوامر أو خيارات CLI القديمة وأوامر CLI الجديدة أو مكافئات الخيارات.

مجموعات الأوامر

مجموعة الأوامر القديمة مجموعة أوامر جديدة
cluster-policies cluster-policies. جميع أسماء الأوامر هي نفسها.
clusters clusters. جميع أسماء الأوامر هي نفسها.
configure configure. راجع خيارات التكوين.
fs fs. راجع أوامر fs.
groups groups. راجع أوامر المجموعات.
instance-pools instance-pools. جميع أسماء الأوامر هي نفسها.
jobs jobs. جميع أسماء الأوامر هي نفسها.
libraries libraries. جميع أسماء الأوامر هي نفسها باستثناء list. list لم يعد الأمر متوفرا؛ استخدم all-cluster-statuses الأوامر أو cluster-status بدلا من ذلك.
pipelines pipelines. راجع أوامر البنية الأساسية لبرنامج ربط العمليات التجارية.
repos repos. جميع أسماء الأوامر هي نفسها.
runs jobs. راجع أوامر التشغيل.
secrets secrets. راجع أوامر الأسرار.
stack غير متوفر في CLI الجديد. توصي Databricks باستخدام موفر Databricks Terraform بدلا من ذلك.
tokens tokens. راجع أوامر الرموز المميزة.
unity-catalog مختلف. راجع مجموعات أوامر كتالوج الوحدة.
workspace workspace. راجع أوامر مساحة العمل.

configure خيارات

الخيار القديم خيار جديد
-o يستخدم -o CLI القديم لمصادقة OAuth. يعيد CLI الجديد استخدام -o لتحديد ما إذا كان إخراج CLI بتنسيق نص أو JSON. لا ينطبق على Azure Databricks.
--oauth لا ينطبق على Azure Databricks.
-s أو --scope لا ينطبق على Azure Databricks.
-t أو --token -t أو --token (نفسه)
-f أو --token-file غير متوفر في CLI الجديد.
--host --host (نفسه)
--aad-token استخدم --host وحدد رمزا مميزا لمعرف Microsoft Entra (المعروف سابقا ب Azure Active Directory) عند مطالبتك بدلا من رمز وصول شخصي ل Azure Databricks.
--insecure غير متوفر في CLI الجديد.
--jobs-api-version غير متوفر في CLI الجديد. يستخدم CLI الجديد واجهة برمجة تطبيقات الوظائف 2.1 فقط. لاستدعاء واجهة برمجة تطبيقات الوظائف القديمة 2.0، استخدم CLI القديم وشاهد Jobs CLI (قديم) .
--debug لتصحيح الأخطاء وتسجيل الدخول إلى CLI الجديد، راجع وضع تتبع الأخطاء.
--profile --profile (نفسه) أو -p
-h أو --help -h أو --help (نفسه)

fs الاوامر

جميع fs الأوامر في CLI القديمة هي نفسها في CLI الجديد، باستثناء fs mv التي لا تتوفر في CLI الجديد.

الأمر القديم أمر جديد
fs cat fs cat (نفسه)
fs cp fs cp (نفسه)
fs ls fs ls (نفسه)
fs mkdirs fs mkdir
fs mv غير متوفر في CLI الجديد.
fs rm fs rm (نفسه)

groups الاوامر

الأمر القديم أمر جديد
groups add-member groups patch
groups create groups create (نفسه)
groups delete groups delete (نفسه)
groups list groups list (نفسه)
groups list-members groups list
groups list-parents groups list
groups remove-member groups patch

pipelines الاوامر

الأمر القديم أمر جديد
pipelines create pipelines create (نفسه)
pipelines delete pipelines delete (نفسه)
pipelines deploy pipelines create
pipelines edit pipelines update
pipelines get pipelines get (نفسه)
pipelines list pipelines list-pipeline-events أو pipelines list-pipelines أو pipelines list-updates
pipelines reset pipelines reset (نفسه)
pipelines start pipelines start update
pipelines stop pipelines stop (نفسه)
pipelines update pipelines update (نفسه)

runs الاوامر

الأمر القديم أمر جديد
runs cancel jobs cancel-run
runs get jobs get-run
runs get-output jobs get-run-output
runs list jobs list-runs
runs submit jobs submit

secrets الاوامر

الأمر القديم أمر جديد
secrets create-scope secrets create-scope (نفسه)
secrets delete secrets delete-secret
secrets delete-acl secrets delete-acl (نفسه)
secrets delete-scope secrets delete-scope (نفسه)
secrets get-acl secrets get-acl (نفسه)
secrets list secrets list-secrets
secrets list-acls secrets list-acls (نفسه)
secrets list-scopes secrets list-scopes (نفسه)
secrets put secrets put-secret
secrets put-acl secrets put-acl (نفسه)
secrets write secrets put-secret
secrets write-acl secrets put-acl

tokens الاوامر

الأمر القديم أمر جديد
tokens create tokens create (نفسه)
tokens list tokens list (نفسه)
tokens revoke tokens delete

unity-catalog مجموعات الأوامر

unity-catalog <command> في CLI القديم يصبح فقط <command> في CLI الجديد.

مجموعة الأوامر القديمة مجموعة أوامر جديدة
unity-catalog catalogs catalogs (نفسه ولكن إسقاط unity-catalog)
unity-catalog external-locations external-locations (نفسه ولكن إسقاط unity-catalog)
unity-catalog lineage غير متوفر في CLI الجديد. راجع استرداد دورة حياة البيانات باستخدام واجهة برمجة تطبيقات REST دورة حياة البيانات.
unity-catalog metastores metastores (نفسه ولكن إسقاط unity-catalog)
unity-catalog permissions grants
unity-catalog providers providers (نفسه ولكن إسقاط unity-catalog)
unity-catalog recipients recipients (نفسه ولكن إسقاط unity-catalog)
unity-catalog schemas schemas (نفسه ولكن إسقاط unity-catalog)
unity-catalog shares shares (نفسه ولكن إسقاط unity-catalog)
unity-catalog storage-credentials storage-credentials (نفسه ولكن إسقاط unity-catalog)
unity-catalog tables tables (نفسه ولكن إسقاط unity-catalog)

workspace الاوامر

الأمر القديم أمر جديد
workspace delete workspace delete (نفسه)
workspace export workspace export (نفسه)
workspace export-dir workspace export
workspace import workspace import (نفسه)
workspace import-dir workspace import
workspace list workspace list (نفسه)
workspace ls workspace list
workspace mkdirs workspace mkdirs (نفسه)
workspace rm workspace delete

الوسيطات الافتراضية والموضعية

تحتوي معظم أوامر CLI الجديدة على وسيطة افتراضية واحدة على الأقل لا تحتوي على خيار مصاحب. تحتوي بعض أوامر CLI الجديدة على وسيطتين موضعيتين أو أكثر يجب تحديدهما بترتيب معين ولا تحتوي على خيارات مصاحبة. يختلف هذا عن CLI القديم، حيث تتطلب معظم الأوامر تحديد خيارات لكافة الوسيطات. على سبيل المثال، يأخذ أمر CLI clusters get الجديد معرف نظام المجموعة كوسيطة افتراضية. ومع ذلك، يتطلب منك أمر CLI clusers get القديم تحديد خيار --cluster-id جنبا إلى جنب مع معرف نظام المجموعة. على سبيل المثال:

بالنسبة إلى CLI القديم:

# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d

# This does **not** work with the legacy CLI - "Error:
#   Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d

بالنسبة إلى CLI الجديد:

# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d

# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d

كمثال آخر، يأخذ أمر CLI grants get الجديد وسيطتين افتراضيتين: النوع القابل للتأمين متبوعا بالاسم الكامل القابل للتأمين. ومع ذلك، يتطلب منك أمر CLI unity-catalog permissions get القديم تحديد خيار --<securable-type> جنبا إلى جنب مع الاسم الكامل القابل للتأمين. على سبيل المثال:

بالنسبة إلى CLI القديم:

databricks unity-catalog permissions get --schema main.default

بالنسبة إلى CLI الجديد:

# This works with the new CLI.
databricks grants get schema main.default

# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default

وضع تصحيح الأخطاء

يوفر CLI القديم خيارا --debug لإظهار تتبع المكدس الكامل عند الخطأ. بالنسبة إلى CLI الجديد، لم يتم التعرف على --debug الخيار. بدلا من ذلك، استخدم الخيارات التالية:

  • استخدم --log-file <path> لكتابة معلومات السجل إلى الملف المحدد في <path>. إذا لم يتم توفير هذا الخيار، يتم إخراج معلومات السجل إلى stderr. --log-file تحديد دون تحديد --log-level نتائج أيضا في عدم كتابة معلومات السجل إلى الملف.
  • استخدم --log-format <type> لتحديد تنسيق المعلومات المسجلة. <type> يمكن أن يكون text (الافتراضي، إذا لم يتم تحديده) أو json.
  • يستخدم --log-level <format> لتحديد مستوى المعلومات المسجلة. القيم المسموح بها هي disabled (الافتراضي، إن لم يتم تحديده)، traceو debugوwarninfo.error

بالنسبة إلى CLI القديم، يوضح المثال التالي تتبع المكدس الكامل عند الخطأ:

databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

بالنسبة إلى CLI الجديد، يسجل المثال التالي تتبع المكدس الكامل إلى ملف مسمى new-cli-errors.log في دليل العمل الحالي. تتم كتابة تتبع المكدس إلى الملف بتنسيق JSON:

databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace

# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)

الأسئلة الشائعة

يسرد هذا القسم الأسئلة الشائعة حول الترحيل من القديم إلى CLI الجديد.

ماذا يحدث لواجهة سطر الأوامر القديمة؟

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

كان CLI القديم دائما في حالة تجريبية مع إخلاء المسؤولية عن أن Databricks لا تخطط أي عمل ميزة جديدة ل CLI القديمة، ولا يتم دعم CLI القديم من خلال قنوات دعم Databricks.

متى سيتم إهمال CLI القديم؟

كان CLI القديم دائما في حالة تجريبية مع إخلاء المسؤولية عن أن Databricks لا تخطط أي عمل ميزة جديدة ل CLI القديمة، ولا يتم دعم CLI القديم من خلال قنوات دعم Databricks.

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

متى سيتم إصدار CLI الجديد كما هو متاح بشكل عام (GA)؟

لم يتم إنشاء تاريخ إصدار أو مخطط زمني لإصدار CLI الجديد ك GA. سيعتمد هذا على الملاحظات التي يتلقاها Databricks من المستخدمين أثناء المعاينة العامة.

ما هي الاختلافات الرئيسية بين واجهات CLIs القديمة والجديدة؟

  • تم إصدار CLI القديم كحزمة Python. يتم إصدار CLI الجديد كقابل للتنفيذ مستقل ولا يحتاج إلى تثبيت أي تبعيات وقت التشغيل.
  • يحتوي CLI الجديد على تغطية كاملة لواجهات برمجة تطبيقات Databricks REST. لا يقوم CLI القديم بذلك.
  • يتوفر CLI الجديد كمعاينة عامة. يبقى CLI القديم في حالة تجريبية.

هل يحتوي CLI الجديد على تماثل كامل للميزات مع CLI القديم؟

يحتوي CLI الجديد على تغطية لكافة الأوامر تقريبا من CLI القديمة. ومع ذلك، لا سيما غائبة من CLI الجديد هو stacks مجموعة الأوامر في CLI القديمة. أيضا، بعض مجموعات أوامر CLI القديمة مثل unity-catalog وتمت runs إعادة بناء التعليمات البرمجية في مجموعات أوامر جديدة في CLI الجديد. للحصول على إرشادات الترحيل، راجع المعلومات المقدمة سابقا في هذه المقالة.

كيف أعمل الترحيل من القديم إلى CLI الجديد؟

للحصول على إرشادات الترحيل، راجع المعلومات المقدمة سابقا في هذه المقالة. لاحظ أن CLI الجديد ليس استبدالا منسدلة ل CLI القديم ويتطلب بعض الإعداد للانتقال من القديم إلى CLI الجديد.

هل يمكن أن توجد عمليات تثبيت لواجهات CLIs القديمة والجديدة على نفس الجهاز؟

نعم. يمكن أن توجد عمليات تثبيت لواجهات CLIs القديمة والجديدة على نفس الجهاز، ولكن يجب أن تكون موجودة في أدلة مختلفة. نظرا لأن كل من الملفين التنفيذيين مسمى databricks، يجب عليك التحكم في الملف القابل للتنفيذ الذي يتم تشغيله افتراضيا عن طريق تكوين PATH. إذا كنت ترغب في تشغيل CLI الجديد ولكن بطريقة ما عن طريق الخطأ تشغيل CLI القديمة بدلا من ذلك، بشكل افتراضي CLI القديم سيتم تشغيل CLI الجديد مع نفس الوسيطات وإظهار رسالة التحذير التالية:

Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>

Because both are installed and available in PATH,
I assume you are trying to run the newer version.

If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>

كما هو موضح في رسالة التحذير السابقة، يمكنك تعيين DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION متغير البيئة لتعطيل 1 هذا السلوك وتشغيل CLI القديم بدلا من ذلك.

الحصول على المساعدة

للحصول على تعليمات حول الترحيل من CLI القديم إلى CLI الجديد، راجع الموارد التالية: