تكوين مجموعة أصول Databricks

توضح هذه المقالة بناء الجملة لملفات تكوين مجموعة أصول Databricks، والتي تحدد حزم أصول Databricks. راجع ما هي حزم أصول Databricks؟

يجب التعبير عن ملف تكوين المجموعة بتنسيق YAML ويجب أن يحتوي على تعيين حزمة المستوى الأعلى كحد أدنى. يجب أن تحتوي كل مجموعة على ملف تكوين حزمة واحد على الأقل (وواحد فقط) يسمى databricks.yml. إذا كانت هناك ملفات تكوين حزمة متعددة، فيجب الرجوع إليها بواسطة databricks.yml الملف باستخدام include التعيين.

لمزيد من المعلومات حول YAML، راجع مواصفات YAML الرسمية والبرنامج التعليمي.

لإنشاء ملفات تكوين المجموعة والعمل معها، راجع تطوير حزم أصول Databricks.

نظره عامه

يوفر هذا القسم تمثيلا مرئيا لمخطط ملف تكوين المجموعة. للحصول على التفاصيل، راجع التعيينات.

# These is the default bundle configuration if not otherwise overridden in
# the "targets" top-level mapping.
bundle: # Required.
  name: string # Required.
  databricks_cli_version: string
  cluster_id: string
  git:
    origin_url: string
    branch: string

# These are for any custom variables for use throughout the bundle.
variables:
  <some-unique-variable-name>:
    description: string
    default: string or complex

# These are the default workspace settings if not otherwise overridden in
# the following "targets" top-level mapping.
workspace:
  artifact_path: string
  auth_type: string
  azure_client_id: string # For Azure Databricks only.
  azure_environment: string # For Azure Databricks only.
  azure_login_app_id: string # For Azure Databricks only. Non-operational and reserved for future use.
  azure_tenant_id: string # For Azure Databricks only.
  azure_use_msi: true | false # For Azure Databricks only.
  azure_workspace_resource_id: string # For Azure Databricks only.
  client_id: string # For Databricks on AWS only.
  file_path: string
  google_service_account: string # For Databricks on Google Cloud only.
  host: string
  profile: string
  root_path: string
  state_path: string

# These are the permissions to apply to experiments, jobs, models, and pipelines defined
# in the "resources" mapping.
permissions:
  - level: <permission-level>
    group_name: <unique-group-name>
  - level: <permission-level>
    user_name: <unique-user-name>
  - level: <permission-level>
    service_principal_name: <unique-principal-name>

# These are the default artifact settings if not otherwise overridden in
# the following "targets" top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    files:
      - source: string
    path: string
    type: string

# These are any additional configuration files to include.
include:
  - "<some-file-or-path-glob-to-include>"
  - "<another-file-or-path-glob-to-include>"

# This is the identity to use to run the bundle
run_as:
  - user_name: <user-name>
  - service_principal_name: <service-principal-name>

# These are the default job and pipeline settings if not otherwise overridden in
# the following "targets" top-level mapping.
resources:
  experiments:
    <some-unique-programmatic-identifier-for-this-experiment>:
      # See the Experiments API's create experiment request payload reference.
  jobs:
    <some-unique-programmatic-identifier-for-this-job>:
      # See the Jobs API's create job request payload reference.
  models:
    <some-unique-programmatic-identifier-for-this-model>:
      # See the Models API's create model request payload reference.
  pipelines:
    <some-unique-programmatic-identifier-for-this-pipeline>:
      # See the Delta Live Tables API's create pipeline request payload reference.
  schemas:
    <some-unique-programmatic-identifier-for-this-schema>:
      # See the Unity Catalog schema request payload reference.

# These are any additional files or paths to include or exclude.
sync:
  include:
    - "<some-file-or-path-glob-to-include>"
    - "<another-file-or-path-glob-to-include>"
  exclude:
    - "<some-file-or-path-glob-to-exclude>"
    - "<another-file-or-path-glob-to-exclude>"
  paths:
    - "<some-file-or-path-to-synchronize>"

# These are the targets to use for deployments and workflow runs. One and only one of these
# targets can be set to "default: true".
targets:
  <some-unique-programmatic-identifier-for-this-target>:
    artifacts:
      # See the preceding "artifacts" syntax.
    bundle:
      # See the preceding "bundle" syntax.
    cluster_id: string
    default: true | false
    mode: development
    presets:
      <preset>: <value>
    resources:
      # See the preceding "resources" syntax.
    sync:
      # See the preceding "sync" syntax.
    variables:
      <preceding-unique-variable-name>: <non-default-value>
    workspace:
      # See the preceding "workspace" syntax.
    run_as:
      # See the preceding "run_as" syntax.

امثله

إشعار

للحصول على أمثلة التكوين التي توضح ميزات المجموعة وحالات استخدام الحزمة الشائعة، راجع أمثلة تكوين المجموعة ومستودع أمثلة الحزمة في GitHub.

يحدد تكوين مجموعة الأمثلة التالي ملفا محليا باسم hello.py موجود في نفس الدليل مثل ملف databricks.ymlتكوين الحزمة المحلي المسمى . يقوم بتشغيل دفتر الملاحظات هذا كوظيفة باستخدام نظام المجموعة البعيد مع معرف نظام المجموعة المحدد. تتم قراءة عنوان URL لمساحة العمل البعيدة وبيانات اعتماد مصادقة مساحة العمل من ملف تعريف التكوين المحلي للمتصل المسمى DEFAULT.

توصي Databricks باستخدام host التعيين بدلا من default التعيين كلما أمكن ذلك، لأن هذا يجعل ملفات تكوين الحزمة الخاصة بك أكثر قابلية للنقل. host يؤدي تعيين التعيين إلى توجيه Databricks CLI للعثور على ملف تعريف مطابق في ملفك .databrickscfg ثم استخدام حقول ملف التعريف هذا لتحديد نوع مصادقة Databricks الذي يجب استخدامه. إذا كانت هناك ملفات تعريف متعددة مع حقل مطابق host داخل الملف الخاص بك .databrickscfg ، فيجب عليك استخدام profile لإرشاد Databricks CLI حول ملف التعريف المحدد الذي يجب استخدامه. على سبيل المثال، راجع prod الإعلان الهدف لاحقا في هذا القسم.

تمكنك هذه التقنية من إعادة استخدام بالإضافة إلى تجاوز تعريفات الوظيفة وإعداداتها داخل resources الكتلة:

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true

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

bundle:
  name: hello-bundle

targets:
  dev:
    default: true
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 1234-567890-abcde123
              notebook_task:
                notebook_path: ./hello.py

يضيف المثال التالي هدفا بالاسم prod الذي يستخدم عنوان URL مختلف لمساحة العمل البعيدة وبيانات اعتماد مصادقة مساحة العمل، والتي تتم قراءتها من إدخال مطابقة host ملف المتصل .databrickscfg مع عنوان URL المحدد لمساحة العمل. تعمل هذه المهمة على تشغيل دفتر الملاحظات نفسه ولكنها تستخدم مجموعة بعيدة مختلفة مع معرف نظام المجموعة المحدد. لاحظ أنك لا تحتاج إلى الإعلان عن notebook_task التعيين داخل prod التعيين، لأنه يعود لاستخدام notebook_task التعيين داخل تعيين المستوى resources الأعلى، إذا notebook_task لم يتم تجاوز التعيين بشكل صريح داخل prod التعيين.

bundle:
  name: hello-bundle

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

للتحقق من صحة هذه المهمة ونشرها وتشغيلها dev ضمن الهدف:

# Because the "dev" target is set to "default: true",
# you do not need to specify "-t dev":
databricks bundle validate
databricks bundle deploy
databricks bundle run hello_job

# But you can still explicitly specify it, if you want or need to:
databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev hello_job

للتحقق من صحة هذه المهمة ونشرها وتشغيلها prod داخل الهدف بدلا من ذلك:

# You must specify "-t prod", because the "dev" target
# is already set to "default: true":
databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod hello_job

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

databricks.yml:

bundle:
  name: hello-bundle

include:
  - "bundle*.yml"

bundle.resources.yml:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

bundle.targets.yml:

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>
    resources:
      jobs:
        hello-job:
          name: hello-job
          tasks:
            - task_key: hello-task
              existing_cluster_id: 2345-678901-fabcd456

تعيينات

تصف الأقسام التالية بناء جملة ملف تكوين المجموعة، عن طريق تعيين المستوى الأعلى.

• حزم
• المتغيرات
• workspace
• اذونات
• البيانات الاصطناعية
• أدخل
• موارد
• مزامنه
• اهداف

حزم

يجب أن يحتوي ملف تكوين المجموعة على تعيين واحد فقط من المستوى bundle الأعلى يربط محتويات المجموعة وإعدادات مساحة عمل Azure Databricks.

يجب أن يحتوي هذا bundle التعيين على تعيين name يحدد اسما برمجيا (أو منطقيا) للحزمة. يوضح المثال التالي حزمة بالاسم hello-bundleالبرمجي (أو المنطقي).

bundle:
  name: hello-bundle

bundle يمكن أن يكون التعيين أيضا تابعا لواحد أو أكثر من الأهداف في تعيين أهداف المستوى الأعلى. تحدد كل من هذه التعيينات الفرعية bundle أي تجاوزات غير افتراضية على المستوى الهدف. ومع ذلك، لا يمكن تجاوز قيمة تعيين name المستوى bundle الأعلى على المستوى الهدف.

cluster_id

bundle يمكن أن يكون التعيين تعيينا تابعاcluster_id. يمكنك هذا التعيين من تحديد معرف نظام المجموعة لاستخدامه كتجاوز للمجموعات المحددة في مكان آخر في ملف تكوين المجموعة. للحصول على معلومات حول كيفية استرداد معرف نظام مجموعة، راجع عنوان URL للمجموعة ومعرفها.

التجاوز cluster_id مخصص لسيناريوهات التطوير فقط وهو مدعوم فقط للهدف الذي تم تعيين تعيينه mode إلى development. لمزيد من المعلومات حول target التعيين، راجع الأهداف.

compute_id

إشعار

تم إهمال هذا الإعداد. استخدم cluster_id بدلا من ذلك.

bundle يمكن أن يكون التعيين تعيينا تابعاcompute_id. يمكنك هذا التعيين من تحديد معرف نظام المجموعة لاستخدامه كتجاوز للمجموعات المحددة في مكان آخر في ملف تكوين المجموعة.

بوابه

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

كلما قمت بتشغيل bundle أمر مثل validate، deploy أو run، يملأ bundle الأمر شجرة تكوين الأمر بالإعدادات الافتراضية التالية:

• bundle.git.origin_url، الذي يمثل عنوان URL الأصلي للم repo. هذه هي نفس القيمة التي ستحصل عليها إذا قمت بتشغيل الأمر git config --get remote.origin.url من المستودع المستنسخ. يمكنك استخدام الاستبدالات للإشارة إلى هذه القيمة مع ملفات تكوين المجموعة الخاصة بك، ك ${bundle.git.origin_url}.
• bundle.git.branch، الذي يمثل الفرع الحالي داخل المستودع. هذه هي نفس القيمة التي ستحصل عليها إذا قمت بتشغيل الأمر git branch --show-current من المستودع المستنسخ. يمكنك استخدام الاستبدالات للإشارة إلى هذه القيمة مع ملفات تكوين المجموعة الخاصة بك، ك ${bundle.git.branch}.
• bundle.git.commit، الذي يمثل HEAD التثبيت داخل المستودع. هذه هي نفس القيمة التي ستحصل عليها إذا قمت بتشغيل الأمر git rev-parse HEAD من المستودع المستنسخ. يمكنك استخدام الاستبدالات للإشارة إلى هذه القيمة مع ملفات تكوين المجموعة الخاصة بك، ك ${bundle.git.commit}.

لاسترداد إعدادات Git أو تجاوزها، يجب أن تكون مجموعتك داخل دليل مقترن بمستودع Git، على سبيل المثال دليل محلي تتم تهيئته عن طريق تشغيل git clone الأمر. إذا لم يكن الدليل مقترنا بمستودع Git، فإن إعدادات Git هذه فارغة.

يمكنك تجاوز origin_url الإعدادات و branch ضمن git تعيين تعيين المستوى bundle الأعلى إذا لزم الأمر، كما يلي:

bundle:
  git:
    origin_url: <some-non-default-origin-url>
    branch: <some-non-current-branch-name>

databricks_cli_version

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

يتوافق إصدار Databricks CLI مع الإصدار الدلالي ويدعم databricks_cli_version التعيين تحديد قيود الإصدار. إذا لم تكن القيمة الحالية databricks --version ضمن الحدود المحددة في تعيين المجموعة databricks_cli_version ، يحدث خطأ عند databricks bundle validate تنفيذها على المجموعة. توضح الأمثلة التالية بعض بناء جملة قيد الإصدار الشائع:

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.0" # require Databricks CLI 0.218.0

bundle:
  name: hello-bundle
  databricks_cli_version: "0.218.*" # allow all patch versions of Databricks CLI 0.218

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0" # allow any version of Databricks CLI 0.218.0 or higher

bundle:
  name: my-bundle
  databricks_cli_version: ">= 0.218.0, <= 1.0.0" # allow any Databricks CLI version between 0.218.0 and 1.0.0, inclusive

المتغيرات

يمكن أن يحتوي ملف إعدادات الحزم على تعيين مستوى أعلى variables واحد حيث يتم تعريف المتغيرات المخصصة. لكل متغير، قم بتعيين وصف اختياري، أو قيمة افتراضية، سواء كان المتغير المخصص نوعا معقدا، أو بحث لاسترداد قيمة معرف، باستخدام التنسيق التالي:

variables:
  <variable-name>:
    description: <variable-description>
    default: <optional-default-value>
    type: <optional-type-value> # "complex" is the only valid value
    lookup:
      <optional-object-type>: <optional-object-name>

إشعار

يفترض أن تكون المتغيرات من النوع string، ما لم type يتم تعيين إلى complex. راجع تعريف متغير معقد.

للإشارة إلى متغير مخصص داخل تكوين المجموعة، استخدم الاستبدال ${var.<variable_name>}.

لمزيد من المعلومات حول المتغيرات المخصصة والاستبدالات، راجع الاستبدالات والمتغيرات في حزم أصول Databricks.

مساحه عمل

يمكن أن يحتوي ملف تكوين المجموعة على تعيين واحد فقط من المستوى workspace الأعلى لتحديد أي إعدادات مساحة عمل Azure Databricks غير افتراضية لاستخدامها.

root_path

يمكن أن يحتوي هذا workspace التعيين على تعيين root_path لتحديد مسار جذر غير افتراضي لاستخدامه داخل مساحة العمل لكل من عمليات التوزيع وتشغيل سير العمل، على سبيل المثال:

workspace:
  root_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

بشكل افتراضي، يستخدم root_path Databricks CLI المسار الافتراضي ل /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}، والذي يستخدم الاستبدالات.

artifact_path

يمكن أن يحتوي هذا workspace التعيين أيضا على تعيين artifact_path لتحديد مسار أداة غير افتراضي لاستخدامه داخل مساحة العمل لكل من عمليات النشر وتشغيل سير العمل، على سبيل المثال:

workspace:
  artifact_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/artifacts

بشكل افتراضي، يستخدم artifact_path Databricks CLI المسار الافتراضي ل ${workspace.root}/artifacts، والذي يستخدم الاستبدالات.

إشعار

artifact_path لا يدعم التعيين مسارات نظام ملفات Databricks (DBFS).

file_path

يمكن أن يحتوي هذا workspace التعيين أيضا على تعيين file_path لتحديد مسار ملف غير افتراضي لاستخدامه داخل مساحة العمل لكل من عمليات النشر وتشغيل سير العمل، على سبيل المثال:

workspace:
  file_path: /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}/files

بشكل افتراضي، يستخدم file_path Databricks CLI المسار الافتراضي ل ${workspace.root}/files، والذي يستخدم الاستبدالات.

state_path

تعيين state_path افتراضي إلى المسار الافتراضي ل ${workspace.root}/state ويمثل المسار داخل مساحة العمل الخاصة بك لتخزين معلومات حالة Terraform حول عمليات النشر.

تعيينات مساحة العمل الأخرى

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

هام

يجب عليك قيم التعليمات البرمجية الثابتة للت تعيينات التالية workspace لمصادقة Azure Databricks. على سبيل المثال، لا يمكنك تحديد متغيرات مخصصة لقيم هذه التعيينات باستخدام بناء الجملة ${var.*} .

• profile يحدد التعيين (أو الخيارات أو --profile -p عند تشغيل الحزمة التحقق من صحة الأوامر ونشرها وتشغيلها وإتلافها باستخدام Databricks CLI) اسم ملف تعريف التكوين لاستخدامه مع مساحة العمل هذه لمصادقة Azure Databricks. يعين ملف تعريف التكوين هذا إلى الملف الذي قمت بإنشائه عند إعداد Databricks CLI.

  إشعار

  توصي Databricks باستخدام host التعيين (أو الخيارات أو --profile -p عند تشغيل الحزمة للتحقق من صحة الأوامر ونشرها وتشغيلها وإتلافها باستخدام Databricks CLI) بدلا من profile التعيين، لأن هذا يجعل ملفات تكوين الحزمة أكثر قابلية للنقل. host يؤدي تعيين التعيين إلى توجيه Databricks CLI للعثور على ملف تعريف مطابق في ملفك .databrickscfg ثم استخدام حقول ملف التعريف هذا لتحديد نوع مصادقة Databricks الذي يجب استخدامه. إذا كانت هناك ملفات تعريف متعددة مع حقل مطابق host داخل الملف الخاص بك .databrickscfg ، فيجب عليك استخدام profile التعيين (أو --profile خيارات سطر الأوامر أو -p ) لإرشاد Databricks CLI حول ملف التعريف الذي يجب استخدامه. على سبيل المثال، راجع prod الإعلان الهدف في الأمثلة.

• host يحدد التعيين عنوان URL لمساحة عمل Azure Databricks. راجع عنوان URL لكل مساحة عمل.

• بالنسبة لمصادقة OAuth من جهاز إلى جهاز (M2M)، يتم استخدام التعيين client_id . بدلا من ذلك، يمكنك تعيين هذه القيمة في متغير DATABRICKS_CLIENT_IDالبيئة المحلية . أو يمكنك إنشاء ملف تعريف تكوين بالقيمة client_id ثم تحديد اسم ملف التعريف مع profile التعيين (أو باستخدام --profile الخيارات أو -p عند تشغيل الحزمة التحقق من صحة الأوامر ونشرها وتشغيلها وإتلافها باستخدام Databricks CLI). راجع مصادقة الوصول إلى Azure Databricks باستخدام كيان خدمة باستخدام OAuth (OAuth M2M).

  إشعار

  لا يمكنك تحديد قيمة سرية ل Azure Databricks OAuth في ملف تكوين المجموعة. بدلا من ذلك، قم بتعيين متغير DATABRICKS_CLIENT_SECRETالبيئة المحلية . أو يمكنك إضافة client_secret القيمة إلى ملف تعريف التكوين ثم تحديد اسم ملف التعريف مع profile التعيين (أو باستخدام --profile الخيارات أو -p عند تشغيل الحزمة التحقق من صحة الأوامر ونشرها وتشغيلها وإتلافها باستخدام Databricks CLI).

• بالنسبة لمصادقة Azure CLI، يتم استخدام التعيين azure_workspace_resource_id . بدلا من ذلك، يمكنك تعيين هذه القيمة في متغير DATABRICKS_AZURE_RESOURCE_IDالبيئة المحلية . أو يمكنك إنشاء ملف تعريف تكوين بالقيمة azure_workspace_resource_id ثم تحديد اسم ملف التعريف مع profile التعيين (أو باستخدام --profile الخيارات أو -p عند تشغيل الحزمة التحقق من صحة الأوامر ونشرها وتشغيلها وإتلافها باستخدام Databricks CLI). راجع مصادقة Azure CLI.

• بالنسبة للمصادقة السرية لعميل Azure مع كيانات الخدمة، يتم استخدام التعيينات azure_workspace_resource_idazure_tenant_idو وazure_client_id. بدلا من ذلك، يمكنك تعيين هذه القيم في متغيرات DATABRICKS_AZURE_RESOURCE_IDالبيئة المحلية و ARM_TENANT_IDو و ARM_CLIENT_IDعلى التوالي. أو يمكنك إنشاء ملف تعريف تكوين بالقيم azure_workspace_resource_idazure_tenant_idو azure_client_id و ثم تحديد اسم ملف التعريف مع profile التعيين (أو باستخدام --profile الخيارات أو -p عند تشغيل الحزمة تحقق من صحة الأوامر ونشرها وتشغيلها وإتلافها باستخدام Databricks CLI). راجع المصادقة الأساسية لخدمة MS Entra.

  إشعار

  لا يمكنك تحديد قيمة سرية لعميل Azure في ملف تكوين المجموعة. بدلا من ذلك، قم بتعيين متغير ARM_CLIENT_SECRETالبيئة المحلية . أو يمكنك إضافة azure_client_secret القيمة إلى ملف تعريف التكوين ثم تحديد اسم ملف التعريف مع profile التعيين (أو باستخدام --profile الخيارات أو -p عند تشغيل الحزمة التحقق من صحة الأوامر ونشرها وتشغيلها وإتلافها باستخدام Databricks CLI).

• بالنسبة لمصادقة الهويات المدارة من Azure، يتم استخدام التعيينات azure_use_msiazure_client_idو وazure_workspace_resource_id. بدلا من ذلك، يمكنك تعيين هذه القيم في متغيرات ARM_USE_MSIالبيئة المحلية و ARM_CLIENT_IDو و DATABRICKS_AZURE_RESOURCE_IDعلى التوالي. أو يمكنك إنشاء ملف تعريف تكوين بالقيم azure_use_msiazure_client_idو azure_workspace_resource_id و ثم تحديد اسم ملف التعريف مع profile التعيين (أو باستخدام --profile الخيارات أو -p عند تشغيل الحزمة تحقق من صحة الأوامر ونشرها وتشغيلها وإتلافها باستخدام Databricks CLI). راجع مصادقة الهويات المدارة من Azure.

• azure_environment يحدد التعيين نوع بيئة Azure (مثل Public وUsGov والصين وألمانيا) لمجموعة معينة من نقاط نهاية API. القيمة الافتراضية هي PUBLIC. بدلا من ذلك، يمكنك تعيين هذه القيمة في متغير ARM_ENVIRONMENTالبيئة المحلية . أو يمكنك إضافة azure_environment القيمة إلى ملف تعريف التكوين ثم تحديد اسم ملف التعريف مع profile التعيين (أو باستخدام --profile الخيارات أو -p عند تشغيل الحزمة التحقق من صحة الأوامر ونشرها وتشغيلها وإتلافها باستخدام Databricks CLI).

• التعيين azure_login_app_id غير تشغيلي ومحفوظ للاستخدام الداخلي.

• auth_type يحدد التعيين نوع مصادقة Azure Databricks لاستخدامه، خاصة في الحالات التي يستنتج فيها Databricks CLI نوع مصادقة غير متوقع. راجع الوصول إلى المصادقة إلى موارد Azure Databricks.

اذونات

يحدد تعيين المستوى permissions الأعلى مستوى أذونات واحدا أو أكثر لتطبيقه على جميع الموارد المحددة في المجموعة. إذا كنت تريد تطبيق الأذونات على مورد معين، فشاهد تعريف الأذونات لمورد معين.

مستويات أذونات المستوى الأعلى المسموح بها هي CAN_VIEWو CAN_MANAGEو.CAN_RUN

يحدد المثال التالي في ملف تكوين المجموعة مستويات الأذونات للمستخدم والمجموعة ومدير الخدمة، والتي يتم تطبيقها على جميع المهام والتدفقات والتجارب والنماذج المحددة في resources المجموعة:

permissions:
  - level: CAN_VIEW
    group_name: test-group
  - level: CAN_MANAGE
    user_name: someone@example.com
  - level: CAN_RUN
    service_principal_name: 123456-abcdef

التحف

يحدد تعيين المستوى artifacts الأعلى واحدا أو أكثر من البيانات الاصطناعية التي يتم إنشاؤها تلقائيا أثناء عمليات نشر الحزمة ويمكن استخدامها لاحقا في تشغيل الحزمة. يدعم كل عنصر تابع التعيينات التالية:

• type مطلوب. لإنشاء ملف عجلة Python قبل النشر، يجب تعيين هذا التعيين إلى whl.
• path هو مسار اختياري نسبي من موقع ملف تكوين المجموعة إلى موقع ملف عجلة setup.py Python. إذا path لم يتم تضمينه، فسيحاول Databricks CLI العثور على ملف ملف setup.py عجلة Python في جذر الحزمة.
• files هو تعيين اختياري يتضمن تعيينا تابعا source ، والذي يمكنك استخدامه لتحديد مواقع غير افتراضية لتضمينها للحصول على إرشادات الإنشاء المعقدة. يتم تحديد المواقع كمسارات نسبية من موقع ملف تكوين المجموعة.
• build هي مجموعة اختيارية من أوامر الإنشاء غير الافتراضية التي تريد تشغيلها محليا قبل النشر. بالنسبة إلى إصدارات عجلة Python، يفترض Databricks CLI أنه يمكنه العثور على تثبيت محلي لحزمة Python wheel لتشغيل البنيات، ويقوم بتشغيل الأمر python setup.py bdist_wheel بشكل افتراضي أثناء كل نشر حزمة. لتحديد أوامر بناء متعددة، افصل كل أمر بأحرف علامة العطف المزدوجة (&&).

لمزيد من المعلومات، بما في ذلك عينة الحزمة التي تستخدم artifacts، راجع تطوير ملف عجلة Python باستخدام حزم أصول Databricks.

تلميح

يمكنك تحديد إعدادات البيانات الاصطناعية في الحزم ودمجها وتجاوزها باستخدام التقنيات الموضحة في تعريف إعدادات البيانات الاصطناعية ديناميكيا في Databricks Asset Bundles.

أدخل

include يحدد الصفيف قائمة globs للمسار التي تحتوي على ملفات التكوين لتضمينها داخل المجموعة. نسبة globs للمسار هذه إلى موقع ملف تكوين الحزمة الذي يتم فيه تحديد globs المسار.

لا يتضمن Databricks CLI أي ملفات تكوين بشكل افتراضي داخل المجموعة. يجب استخدام include الصفيف لتحديد أي وجميع ملفات التكوين لتضمينها داخل المجموعة، بخلاف databricks.yml الملف نفسه.

يمكن أن يظهر هذا include الصفيف فقط كرسم خرائط من المستوى الأعلى.

يتضمن تكوين المثال التالي ثلاثة ملفات تكوين. توجد هذه الملفات في نفس المجلد مثل ملف تكوين الحزمة:

include:
  - "bundle.artifacts.yml"
  - "bundle.resources.yml"
  - "bundle.targets.yml"

يتضمن تكوين المثال التالي جميع الملفات مع أسماء الملفات التي تبدأ ب bundle وتنتهي ب .yml. توجد هذه الملفات في نفس المجلد مثل ملف تكوين الحزمة:

include:
  - "bundle*.yml"

موارد

resources يحدد التعيين معلومات حول موارد Azure Databricks المستخدمة من قبل المجموعة.

يمكن أن يظهر هذا resources التعيين كخرائط من المستوى الأعلى، أو يمكن أن يكون تابعا لواحد أو أكثر من الأهداف في تعيين أهداف المستوى الأعلى، ويتضمن صفرا أو أحد أنواع الموارد المدعومة. يتضمن كل تعيين نوع مورد إعلان مورد فردي واحد أو أكثر، والذي يجب أن يكون لكل منها اسم فريد. تستخدم إعلانات الموارد الفردية هذه حمولة طلب عملية إنشاء الكائن المقابل، المعبر عنها في YAML، لتعريف المورد. الخصائص المدعومة لمورد هي الحقول المعتمدة للكائن المقابل.

يتم توثيق حمولات طلب عملية الإنشاء في مرجع Databricks REST API، ويخرج databricks bundle schema الأمر جميع مخططات الكائنات المدعومة. بالإضافة إلى ذلك، databricks bundle validate يقوم الأمر بإرجاع تحذيرات إذا تم العثور على خصائص مورد غير معروفة في ملفات تكوين المجموعة.

يسرد الجدول التالي أنواع الموارد المدعومة للحزم والارتباطات إلى الوثائق على حمولاتها المقابلة.

نوع المورد	تعيينات الموارد
العناقيد	تعيينات المجموعات: POST /api/2.1/jobs/create
مهمة	تعيينات الوظائف: POST /api/2.1/jobs/create للحصول على معلومات إضافية، راجع أنواع مهام الوظيفة وتجاوز إعدادات مجموعة الوظائف الجديدة.
خط انابيب	تعيينات البنية الأساسية لبرنامج ربط العمليات التجارية: POST /api/2.0/pipelines/create
التجربه	تعيينات التجربة: POST /api/2.0/mlflow/experiments/create
نموذج	تعيينات النموذج: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint	تعيينات نقطة نهاية خدمة النموذج: POST /api/2.0/serving-endpoints/create
registered_model (كتالوج Unity)	تعيينات نموذج كتالوج Unity: POST /api/2.1/unity-catalog/models/create
مخطط (كتالوج Unity)	تعيينات مخطط كتالوج Unity: POST /api/2.1/unity-catalog/schemas/create

ترتبط جميع المسارات إلى المجلدات والملفات المشار إليها بواسطة إعلانات الموارد بموقع ملف تكوين المجموعة الذي يتم تحديد هذه المسارات فيه.

نظم المجموعات

clusters يسمح لك المورد بإنشاء مجموعات لجميع الأغراض. ينشئ المثال التالي نظام مجموعة باسم my_cluster ويعين ذلك كمجموعة لاستخدامها لتشغيل دفتر الملاحظات في my_job:

bundle:
  name: clusters

resources:
  clusters:
    my_cluster:
      num_workers: 2
      node_type_id: "i3.xlarge"
      autoscale:
        min_workers: 2
        max_workers: 7
      spark_version: "13.3.x-scala2.12"
      spark_conf:
        "spark.executor.memory": "2g"

  jobs:
    my_job:
      tasks:
        - task_key: test_task
          existing_cluster_id: ${resources.clusters.my_cluster.id}
          notebook_task:
            notebook_path: "./src/my_notebook.py"

المهمة

يوضح المثال التالي وظيفة باستخدام مفتاح المورد ل hello-job:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py

pipeline

يوضح المثال التالي البنية الأساسية لبرنامج ربط العمليات التجارية مع مفتاح المورد ل hello-pipeline:

resources:
  pipelines:
    hello-pipeline:
      name: hello-pipeline
      clusters:
        - label: default
          num_workers: 1
      development: true
      continuous: false
      channel: CURRENT
      edition: CORE
      photon: false
      libraries:
        - notebook:
            path: ./pipeline.py

Schema

schema يسمح لك نوع المورد بتعريف مخططات كتالوج Unity للجداول والأصول الأخرى في مهام سير العمل والتدفقات التي تم إنشاؤها كجزء من مجموعة. يحتوي المخطط، الذي يختلف عن أنواع الموارد الأخرى، على القيود التالية:

• دائما ما يكون مالك مورد المخطط هو مستخدم النشر، ولا يمكن تغييره. إذا run_as تم تحديده في المجموعة، تجاهله بواسطة العمليات على المخطط.
• تتوفر فقط الحقول التي يدعمها كائن المخططات المقابل إنشاء API للمورد schema . على سبيل المثال، enable_predictive_optimization غير مدعوم لأنه متوفر فقط على واجهة برمجة تطبيقات التحديث.

يوضح المثال التالي البنية الأساسية لبرنامج ربط العمليات التجارية مع مفتاح my_pipeline المورد الذي ينشئ مخطط كتالوج Unity مع المفتاح my_schema كهدف:

resources:
  pipelines:
    my_pipeline:
      name: test-pipeline-{{.unique_id}}
      libraries:
        - notebook:
            path: ./nb.sql
      development: true
      catalog: main
      target: ${resources.schemas.my_schema.id}

  schemas:
    my_schema:
      name: test-schema-{{.unique_id}}
      catalog_name: main
      comment: This schema was created by DABs.

لا تدعم حزم أصول Databricks تعيين المنح ذات المستوى الأعلى، لذا إذا كنت تريد تعيين منح لمخطط، فحدد المنح للمخطط داخل schemas التعيين:

schemas:
    my_schema:
      name: test-schema
      grants:
        - principal: users
          privileges:
            - CAN_MANAGE
        - principal: my_team
          privileges:
            - CAN_READ
      catalog_name: main
      comment: "my schema with grants"

مزامنه

sync يسمح لك التعيين بتكوين الملفات التي تعد جزءا من عمليات نشر الحزمة الخاصة بك.

تضمين واستبعاد

include تحدد التعيينات و exclude ضمن sync التعيين قائمة بالملفات أو المجلدات لتضمينها ضمن عمليات النشر المجمعة أو استبعادها منها، استنادا إلى القواعد التالية:

• استنادا إلى أي قائمة من ملفات ومسار globs في .gitignore ملف في جذر الحزمة، include يمكن أن يحتوي التعيين على قائمة globs الملفات أو globs المسار أو كليهما، بالنسبة لجذر الحزمة، لتضمينها بشكل صريح.
• استنادا إلى أي قائمة من ملفات ومسار globs في .gitignore ملف في جذر الحزمة، بالإضافة إلى قائمة globs للملف والمسار في include التعيين، exclude يمكن أن يحتوي التعيين على قائمة globs الملفات أو globs المسار أو كليهما، بالنسبة إلى جذر المجموعة، لاستبعادها بشكل صريح.

ترتبط جميع المسارات إلى الملفات والمجلدات المحددة بموقع ملف تكوين المجموعة الذي تم تحديدها فيه.

يتبع بناء الجملة ل include وأنماط exclude الملف والمسار بناء جملة النمط القياسي .gitignore . راجع تنسيق نمط gitignore.

على سبيل المثال، إذا كان الملف التالي .gitignore يحتوي على الإدخالات التالية:

.databricks
my_package/dist

ويحتوي ملف تكوين المجموعة على التعيين التالي include :

sync:
  include:
    - my_package/dist/*.whl

ثم يتم تضمين جميع الملفات في my_package/dist المجلد مع ملحق *.whl ملف. لا يتم تضمين أي ملفات أخرى في my_package/dist المجلد.

ومع ذلك، إذا كان ملف تكوين الحزمة يحتوي أيضا على التعيين التالي exclude :

sync:
  include:
    - my_package/dist/*.whl
  exclude:
    - my_package/dist/delete-me.whl

ثم يتم تضمين كافة الملفات الموجودة my_package/dist في المجلد مع ملحق *.whlملف ، باستثناء الملف المسمى delete-me.whl. أي ملفات أخرى في my_package/dist المجلد غير مضمنة أيضا.

sync يمكن أيضا الإعلان عن التعيين في targets التعيين لهدف معين. يتم دمج أي sync تعيين تم الإعلان عنه في هدف مع أي إعلانات تعيين من المستوى sync الأعلى. على سبيل المثال، متابعة مع المثال السابق، يدمج التعيين التالي include على المستوى مع include التعيين في تعيين المستوى sync targets الأعلى:

targets:
  dev:
    sync:
      include:
        - my_package/dist/delete-me.whl

المسارات

sync يمكن أن يحتوي التعيين على تعيين paths يحدد المسارات المحلية للمزامنة مع مساحة العمل. paths يسمح لك التعيين بمشاركة الملفات الشائعة عبر الحزم، ويمكن استخدامه لمزامنة الملفات الموجودة خارج جذر المجموعة. (جذر المجموعة هو موقع ملف databricks.yml.) يكون هذا مفيدا بشكل خاص عندما يكون لديك مستودع واحد يستضيف مجموعات متعددة ويرغب في مشاركة المكتبات أو ملفات التعليمات البرمجية أو التكوين.

يجب أن تكون المسارات المحددة نسبة إلى الملفات والدلائل المثبتة في المجلد حيث paths تم تعيين التعيين. إذا اجتازت قيمة مسار واحدة أو أكثر الدليل إلى أصل جذر الحزمة، يتم تحديد مسار الجذر ديناميكيا للتأكد من أن بنية المجلد تظل سليمة. على سبيل المثال، إذا تمت تسمية my_bundle مجلد جذر الحزمة، فإن هذا التكوين في databricks.yml يقوم بمزامنة common المجلد الموجود أعلى مستوى واحد من جذر الحزمة وجذر المجموعة نفسه:

sync:
  paths:
    - ../common
    - .

يؤدي نشر هذه المجموعة إلى بنية المجلد التالية في مساحة العمل:

common/
  common_file.txt
my_bundle/
  databricks.yml
  src/
    ...

اهداف

targets يحدد التعيين سياقا واحدا أو أكثر لتشغيل سير عمل Azure Databricks. كل هدف هو مجموعة فريدة من البيانات الاصطناعية وإعدادات مساحة عمل Azure Databricks ومهمة Azure Databricks أو تفاصيل البنية الأساسية لبرنامج ربط العمليات التجارية.

targets يتكون التعيين من تعيين هدف واحد أو أكثر، والتي يجب أن يكون لكل منها اسم برمجي فريد (أو منطقي).

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

يتم استخدام الإعدادات في مساحة العمل ذات المستوى الأعلى والبيانات الاصطناعية وتعيينات الموارد إذا لم يتم تحديدها في targets تعيين، ولكن يتم تجاوز أي إعدادات متعارضة بواسطة الإعدادات داخل الهدف.

يمكن أن يتجاوز الهدف أيضا قيم أي متغيرات من المستوى الأعلى.

افتراضي

لتحديد هدف افتراضي لأوامر المجموعة، قم بتعيين default التعيين إلى true. على سبيل المثال، هذا الهدف المسمى dev هو الهدف الافتراضي:

targets:
  dev:
    default: true

إذا لم يتم تكوين هدف افتراضي، أو إذا كنت تريد التحقق من صحة المهام أو المسارات ونشرها وتشغيلها داخل هدف معين، فاستخدم -t خيار أوامر المجموعة.

تتحقق الأوامر التالية من صحة الأهداف و ونشرها وتشغيلها my_job ضمن dev أهداف و prod :

databricks bundle validate
databricks bundle deploy -t dev
databricks bundle run -t dev my_job

databricks bundle validate
databricks bundle deploy -t prod
databricks bundle run -t prod my_job

يوضح المثال التالي هدفين. الهدف الأول له الاسم dev وهو الهدف الافتراضي المستخدم عندما لا يتم تحديد هدف لأوامر المجموعة. الهدف الثاني له الاسم prod ويستخدم فقط عند تحديد هذا الهدف لأوامر الحزمة.

targets:
  dev:
    default: true
  prod:
    workspace:
      host: https://<production-workspace-url>

الوضع و الإعدادات المسبقة

لتسهيل التطوير السهل وأفضل ممارسات CI/CD، توفر Databricks Asset Bundles أوضاع نشر للأهداف التي تحدد السلوكيات الافتراضية لسير عمل ما قبل الإنتاج والإنتاج. بعض السلوكيات قابلة للتكوين أيضا. للحصول على التفاصيل، راجع أوضاع نشر مجموعة أصول Databricks.

تلميح

لتعيين هويات التشغيل للحزم، يمكنك تحديد run_as لكل هدف، كما هو موضح في تحديد هوية تشغيل لسير عمل Databricks Asset Bundles.

لتحديد أن الهدف يتم التعامل معه كهدف تطوير، أضف mode تعيين تعيين إلى development. لتحديد أن الهدف يتم التعامل معه كهدف إنتاج، أضف mode تعيين تعيين إلى production. على سبيل المثال، يتم التعامل مع هذا الهدف المسمى prod كهدف إنتاج:

targets:
  prod:
    mode: production

يمكنك تخصيص بعض السلوكيات باستخدام presets التعيين. للحصول على قائمة ب الإعدادات المسبقة المتوفرة، راجع الإعدادات المسبقة المخصصة. يوضح المثال التالي هدف إنتاج مخصص يقوم ببادئ وعلامات جميع موارد الإنتاج:

targets:
  prod:
    mode: production
    presets:
      name_prefix: "production_"  # prefix all resource names with production_
      tags:
        prod: true

إذا تم تعيين كل من mode و presets ، تتجاوز الإعدادات المسبقة سلوك الوضع الافتراضي. تتجاوز إعدادات الموارد الفردية الإعدادات المسبقة. على سبيل المثال، إذا تم تعيين جدول إلى UNPAUSED، ولكن trigger_pause_status تم تعيين الإعداد المسبق إلى PAUSED، إلغاء دفع الجدول الزمني.