الاستبدالات والمتغيرات في حزم أصول Databricks

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

تلميح

يمكنك أيضا استخدام مراجع القيمة الديناميكية لقيم معلمات الوظيفة لتمرير سياق حول تشغيل وظيفة إلى مهام الوظيفة. راجع ما هو مرجع القيمة الديناميكية؟ ومعلمات المهام.

استبدال

يمكنك استخدام الاستبدالات لاسترداد قيم الإعدادات التي تتغير استنادا إلى سياق نشر المجموعة وتشغيلها.

على سبيل المثال، عند تشغيل bundle validate --output json الأمر، قد ترى رسما بيانيا مثل هذا:

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "...": "...",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

يمكن استخدام القوالب الفرعية للإشارة إلى قيم حقول الحزمة nameوالحزمة targetومساحة userName العمل لإنشاء مساحة root_path العمل في ملف تكوين المجموعة:

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

يمكنك أيضا إنشاء استبدالات للموارد المسماة. على سبيل المثال، بالنسبة للمسار الذي تم تكوينه بالاسم my_pipeline، ${resources.pipelines.my_pipeline.target} هو استبدال لقيمة الهدف من my_pipeline.

لتحديد الاستبدالات الصالحة، يمكنك استخدام التسلسل الهرمي للمخطط الموثق في مرجع REST API أو إخراج bundle schema الأمر.

فيما يلي بعض الاستبدالات شائعة الاستخدام:

• ${bundle.name}
• ${bundle.target} # Use this substitution instead of ${bundle.environment}
• ${workspace.host}
• ${workspace.current_user.short_name}
• ${workspace.current_user.userName}
• ${workspace.file_path}
• ${workspace.root_path}
• ${resources.jobs.<job-name>.id}
• ${resources.models.<model-name>.name}
• ${resources.pipelines.<pipeline-name>.name}

المتغيرات المخصصة

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

يحدد تكوين المثال التالي المتغيرات my_cluster_id و my_notebook_path:

variables:
  my_cluster_id:
    description: The ID of an existing cluster.
    default: 1234-567890-abcde123
  my_notebook_path:
    description: The path to an existing notebook.
    default: ./hello.py

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

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

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: ${var.my_cluster_id}
          notebook_task:
            notebook_path: ${var.my_notebook_path}

تعيين قيمة متغير

إذا لم تقم بتوفير default قيمة لمتغير، أو إذا كنت تريد تجاوز default قيمة متغير مؤقتا، فوفر القيمة المؤقتة الجديدة للمتغير باستخدام أحد الأساليب التالية:

• قم بتوفير قيمة المتغير كجزء من bundle أمر مثل validateأو deployأو run. للقيام بذلك، استخدم الخيار --var="<key>=<value>"، حيث <key> هو اسم المتغير، وهو <value> قيمة المتغير. على سبيل المثال، كجزء من bundle validate الأمر ، لتوفير قيمة 1234-567890-abcde123 للمتغير المسمى my_cluster_id، ولتوفر قيمة ./hello.py للمتغير المسمى my_notebook_path، قم بتشغيل:

  databricks bundle validate --var="my_cluster_id=1234-567890-abcde123,my_notebook_path=./hello.py"
  
  # Or:
  databricks bundle validate --var="my_cluster_id=1234-567890-abcde123" --var="my_notebook_path=./hello.py"
  

• توفير قيمة المتغير عن طريق تعيين متغير بيئة. يجب أن يبدأ اسم متغير البيئة ب BUNDLE_VAR_. لتعيين متغيرات البيئة، راجع وثائق نظام التشغيل الخاص بك. على سبيل المثال، لتوفير قيمة 1234-567890-abcde123 للمتغير المسمى my_cluster_id، ولتوفر قيمة ./hello.py للمتغير المسمى my_notebook_path، قم بتشغيل الأمر التالي قبل استدعاء أمر bundle مثل validateأو deployأو run:

  بالنسبة إلى Linux وmacOS:

  export BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 && export BUNDLE_VAR_my_notebook_path=./hello.py
  

  لـ Windows:

  "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py"
  

  أو، قم بتوفير قيمة المتغير كجزء من bundle أمر مثل validateأو deployأو run، على سبيل المثال ل Linux وmacOS:

  BUNDLE_VAR_my_cluster_id=1234-567890-abcde123 BUNDLE_VAR_my_notebook_path=./hello.py databricks bundle validate
  

  أو ل Windows:

  "set BUNDLE_VAR_my_cluster_id=1234-567890-abcde123" && "set BUNDLE_VAR_my_notebook_path=./hello.py" && "databricks bundle validate"
  

• قم بتوفير قيمة المتغير داخل ملفات تكوين الحزمة. للقيام بذلك، استخدم تعيينا variables داخل targets التعيين، باتباع هذا التنسيق:

  variables:
    <variable-name>: <value>
  

  على سبيل المثال، لتوفير قيم للمتغيرات المسماة my_cluster_id ولهدفين my_notebook_path منفصلين:

  targets:
    dev:
      variables:
        my_cluster_id: 1234-567890-abcde123
        my_notebook_path: ./hello.py
    prod:
      variables:
        my_cluster_id: 2345-678901-bcdef234
        my_notebook_path: ./hello.py
  

إشعار

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

في الأمثلة السابقة، يبحث Databricks CLI عن قيم المتغيرات my_cluster_id وبالترتيب my_notebook_path التالي، يتوقف عند العثور على قيمة لكل متغير مطابق، متخطاة أي مواقع أخرى لهذا المتغير:

1. ضمن أي --var خيارات محددة كجزء من bundle الأمر.
2. ضمن أي مجموعة متغيرات البيئة التي تبدأ ب BUNDLE_VAR_.
3. ضمن أي variables تعيينات، من بين targets التعيينات داخل ملفات تكوين الحزمة.
4. أي default قيمة لتعريف هذا المتغير، من بين تعيينات المستوى variables الأعلى داخل ملفات تكوين المجموعة الخاصة بك.

تعريف متغير معقد

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

إشعار

القيمة الصالحة الوحيدة للإعداد type هي complex. بالإضافة إلى ذلك، يفشل التحقق من صحة الحزمة إذا type تم تعيين إلى complex وكان default المحدد للمتغير قيمة واحدة.

في المثال التالي، يتم تعريف إعدادات نظام المجموعة داخل متغير معقد مخصص يسمى my_cluster:

variables:
  my_cluster:
    description: "My cluster definition"
    type: complex
    default:
      spark_version: "13.2.x-scala2.11"
      node_type_id: "Standard_DS3_v2"
      num_workers: 2
      spark_conf:
        spark.speculation: true
        spark.databricks.delta.retentionDurationCheck.enabled: false

resources:
  jobs:
    my_job:
      job_clusters:
        - job_cluster_key: my_cluster_key
          new_cluster: ${var.my_cluster}
      tasks:
      - task_key: hello_task
        job_cluster_key: my_cluster_key

استرداد قيمة معرف الكائن

alertclusterinstance_poolpipelinewarehouse dashboardcluster_policymetastorequeryjobservice_principalبالنسبة إلى أنواع الكائنات و، يمكنك تعريف lookup لمتغيرك المخصص لاسترداد معرف كائن مسمى باستخدام هذا التنسيق:

variables:
  <variable-name>:
    lookup:
      <object-type>: "<object-name>"

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

إشعار

يحدث خطأ إذا لم يكن هناك كائن بالاسم المحدد، أو إذا كان هناك أكثر من كائن واحد بالاسم المحدد.

على سبيل المثال، في التكوين التالي، ${var.my_cluster_id} سيتم استبدال بمعرف نظام المجموعة المشترك 12.2.

variables:
  my_cluster_id:
    description: An existing cluster
    lookup:
      cluster: "12.2 shared"

resources:
  jobs:
    my_job:
      name: "My Job"
      tasks:
        - task_key: TestTask
          existing_cluster_id: ${var.my_cluster_id}