Konfigurationer av Databricks Asset Bundle

I den här artikeln beskrivs syntaxen för Databricks Asset Bundle-konfigurationsfiler, som definierar Databricks-tillgångspaket. Se Vad är Databricks-tillgångspaket?

En paketkonfigurationsfil måste uttryckas i YAML-format och måste minst innehålla paketmappningen på den översta nivån. Varje paket måste innehålla minst en (och endast en) paketkonfigurationsfil med namnet databricks.yml. Om det finns flera paketkonfigurationsfiler måste de refereras av databricks.yml filen.

Mer information om YAML finns i den officiella YAML-specifikationen och självstudien.

Information om hur du skapar och arbetar med paketkonfigurationsfiler finns i Utveckling av Databricks-tillgångspaket.

• Översikt
• Exempel
• Mappningar
• Anpassade variabler
• Substitutioner

Översikt

Det här avsnittet innehåller en visuell representation av paketkonfigurationsfilschemat. Mer information finns i Mappningar.

# 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
  compute_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.

# 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>"

# 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.
    compute_id: string
    default: true | false
    mode: development
    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.

Exempel

Följande är ett exempel på en paketkonfigurationsfil. Det här paketet anger fjärrdistributionen av en lokal fil med namnet hello.py som finns i samma katalog som den lokala paketkonfigurationsfilen med namnet databricks.yml. Den kör den här notebook-filen som ett jobb med hjälp av fjärrklustret med det angivna kluster-ID:t. Autentiseringsuppgifterna för fjärrarbetsytans URL och autentiseringsuppgifter för arbetsytan läss från anroparens lokala konfigurationsprofil med namnet DEFAULT.

Kommentar

Databricks rekommenderar att du använder mappningen host i stället för mappningen default där det är möjligt, eftersom det gör paketkonfigurationsfilerna mer portabla. Om du anger mappningen host instrueras Databricks CLI att hitta en matchande profil i .databrickscfg filen och sedan använda profilens fält för att avgöra vilken Databricks-autentiseringstyp som ska användas. Om det finns flera profiler med ett matchande host fält i .databrickscfg filen måste du använda profile för att instruera Databricks CLI om vilken specifik profil som ska användas. Ett exempel finns i måldeklarationen prod senare i det här avsnittet.

Med den här tekniken kan du återanvända och åsidosätta jobbdefinitionerna och inställningarna i resources blocket:

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

Även om följande paketkonfigurationsfil är funktionellt likvärdig, är den inte modulariserad, vilket inte möjliggör bra återanvändning. Den här deklarationen lägger också till en uppgift i jobbet i stället för att åsidosätta det befintliga jobbet:

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

Följande är det tidigare modulariserade exemplet, men med tillägget av ett mål med det programmatiska (eller logiska) namnet prod som använder en annan url för fjärrarbetsyta och autentiseringsuppgifter för arbetsytan, som läss från anroparens filmatchningspost .databrickscfg host med den angivna arbetsytans URL. Det här jobbet kör samma notebook-fil men använder ett annat fjärrkluster med det angivna kluster-ID:t. Observera att du inte behöver deklarera mappningen i mappningen prod eftersom den återgår till att använda mappningen notebook_task i den översta mappningenresources, om mappningen notebook_task inte uttryckligen åsidosätts i mappningenprod.notebook_task

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

Kör följande kommandon för att verifiera, distribuera och köra det här jobbet inom dev målet:

# 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

Kör i stället följande kommandon för att verifiera, distribuera och köra det här jobbet inom prod målet:

# 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

Följande är det föregående exemplet men delas upp i komponentfiler för ännu mer modularisering och bättre återanvändning över flera paketkonfigurationsfiler. Med den här tekniken kan du inte bara återanvända olika definitioner och inställningar, utan du kan också växla ut någon av dessa filer med andra filer som ger helt olika deklarationer:

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

Fler exempel finns i paketexempellagringsplatsen i GitHub.

Mappningar

I följande avsnitt beskrivs syntaxen för paketkonfigurationsfilen efter mappning på den översta nivån.

• knyte
• Variabler
• arbetsyta
• permissions
• Artefakter
• inbegripa
• Resurser
• synkronisering
• Mål

knyte

En paketkonfigurationsfil får bara innehålla en mappning på den översta nivån bundle som associerar paketets innehåll och inställningarna för Azure Databricks-arbetsytan.

Den här bundle mappningen måste innehålla en name mappning som anger ett programmatiskt (eller logiskt) namn för paketet. I följande exempel deklareras ett paket med det programmatiska (eller logiska) namnet hello-bundle.

bundle:
  name: hello-bundle

En bundle mappning kan också vara underordnad ett eller flera av målen i den översta målmappningen . Var och en av dessa underordnade bundle mappningar anger eventuella icke-standard åsidosättningar på målnivå. Det går dock inte att åsidosätta värdet för toppnivåmappningen bundle name på målnivån.

compute_id

Mappningen kan ha en underordnad bundle compute_id mappning. Med den här mappningen kan du ange ID för ett kluster som ska användas som åsidosättning för alla kluster som definierats någon annanstans i paketkonfigurationsfilen. Den här åsidosättningen är avsedd för scenarier med endast utveckling före produktion. Mappningen compute_id fungerar bara för det mål som har mappningen mode inställd på development. Mer information om mappningen compute_id finns i målmappningen.

Git

Du kan hämta och åsidosätta information om Git-versionskontroll som är associerade med ditt paket. Detta är användbart för att kommentera dina distribuerade resurser. Du kanske till exempel vill ta med ursprungs-URL:en för lagringsplatsen i beskrivningen av en maskininlärningsmodell som du distribuerar.

När du kör ett bundle kommando som validate, deploy eller run, bundle fyller kommandots konfigurationsträd med följande standardinställningar:

• bundle.git.origin_url, som representerar lagringsplatsens ursprungs-URL. Det här är samma värde som du skulle få om du körde kommandot git config --get remote.origin.url från din klonade lagringsplats. Du kan använda ersättningar för att referera till det här värdet med dina paketkonfigurationsfiler , som ${bundle.git.origin_url}.
• bundle.git.branch, som representerar den aktuella grenen i lagringsplatsen. Det här är samma värde som du skulle få om du körde kommandot git branch --show-current från din klonade lagringsplats. Du kan använda ersättningar för att referera till det här värdet med dina paketkonfigurationsfiler , som ${bundle.git.branch}.
• bundle.git.commit, som representerar incheckningen HEAD i lagringsplatsen. Det här är samma värde som du skulle få om du körde kommandot git rev-parse HEAD från din klonade lagringsplats. Du kan använda ersättningar för att referera till det här värdet med dina paketkonfigurationsfiler , som ${bundle.git.commit}.

Om du vill hämta eller åsidosätta Git-inställningar måste ditt paket finnas i en katalog som är associerad med en Git-lagringsplats, till exempel en lokal katalog som initieras genom att köra git clone kommandot. Om katalogen inte är associerad med en Git-lagringsplats är de här Git-inställningarna tomma.

Du kan åsidosätta origin_url inställningarna och branch i mappningen git av din toppnivåmappning bundle om det behövs, enligt följande:

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

databricks_cli_version

Mappningen bundle kan innehålla en databricks_cli_version mappning som begränsar den Databricks CLI-version som krävs av paketet. Detta kan förhindra problem som orsakas av mappningar som inte stöds i en viss version av Databricks CLI.

Databricks CLI-versionen överensstämmer med semantisk versionshantering och mappningen databricks_cli_version har stöd för att ange versionsbegränsningar. Om det aktuella databricks --version värdet inte ligger inom de gränser som anges i paketets databricks_cli_version mappning uppstår ett fel när databricks bundle validate det körs i paketet. I följande exempel visas några vanliga syntaxer för versionsbegränsningar:

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

Variabler

Filen med paketinställningar kan innehålla en mappning på den översta nivån variables för att ange de variabelinställningar som ska användas. Se Anpassade variabler.

arbetsyta

Paketkonfigurationsfilen kan bara innehålla en mappning på den översta nivån workspace för att ange eventuella icke-standardinställningar för Azure Databricks-arbetsytor som ska användas.

Den här workspace mappningen kan innehålla en root_path mappning för att ange en icke-standardrotsökväg som ska användas på arbetsytan för både distributioner och arbetsflödeskörningar, till exempel:

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

Som standard root_path använder Databricks CLI standardsökvägen /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}för , som använder substitutioner.

Den här workspace mappningen kan också innehålla en artifact_path mappning för att ange en icke-standardartefaktsökväg som ska användas på arbetsytan för både distributioner och arbetsflödeskörningar, till exempel:

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

Som standard artifact_path använder Databricks CLI standardsökvägen ${workspace.root}/artifactsför , som använder substitutioner.

.. obs! Mappningen artifact_path stöder inte DBFS-sökvägar (Databricks File System).

Den här workspace mappningen kan också innehålla en file_path mappning för att ange en icke-standardfilsökväg som ska användas på arbetsytan för både distributioner och arbetsflödeskörningar, till exempel:

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

Som standard file_path använder Databricks CLI standardsökvägen ${workspace.root}/filesför , som använder substitutioner.

Mappningen state_path är standardsökvägen ${workspace.root}/state för och representerar sökvägen i din arbetsyta för att lagra Terraform-tillståndsinformation om distributioner.

Mappningen workspace kan också innehålla följande valfria mappningar för att ange den Azure Databricks-autentiseringsmekanism som ska användas. Om de inte anges i den här workspace mappningen måste de anges i en workspace mappning som underordnad ett eller flera av målen i den översta målmappningen .

Viktigt!

Du måste hårdkoda värden för följande workspace mappningar för Azure Databricks-autentisering. Du kan till exempel inte ange anpassade variabler för dessa mappningars värden med hjälp av syntaxen ${var.*} .

• Mappningen profile (eller --profile alternativen -p när du kör paketet verifierar, distribuerar, kör och förstör kommandon med Databricks CLI) anger namnet på en konfigurationsprofil som ska användas med den här arbetsytan för Azure Databricks-autentisering. Den här konfigurationsprofilen mappar till den som du skapade när du konfigurerade Databricks CLI.

  Kommentar

  Databricks rekommenderar att du använder mappningen host (eller alternativen eller --profile -p när du kör paketet validerar, distribuerar, kör och förstör kommandon med Databricks CLI) i stället för mappningen profile , eftersom det gör paketkonfigurationsfilerna mer portabla. Om du anger mappningen host instrueras Databricks CLI att hitta en matchande profil i .databrickscfg filen och sedan använda profilens fält för att avgöra vilken Databricks-autentiseringstyp som ska användas. Om det finns flera profiler med ett matchande host fält i .databrickscfg filen måste du använda mappningen profile (eller kommandoradsalternativen --profile -p ) för att instruera Databricks CLI om vilken profil som ska användas. Ett exempel finns i måldeklarationen prod i exemplen.

• Mappningen host anger URL:en för din Azure Databricks-arbetsyta. Se URL per arbetsyta.

• För OAuth-autentisering från dator till dator (M2M) används mappningen client_id . Du kan också ange det här värdet i den lokala miljövariabeln DATABRICKS_CLIENT_ID. Eller så kan du skapa en konfigurationsprofil med client_id värdet och sedan ange profilens namn med mappningen profile (eller genom att använda --profile alternativen eller -p när du kör paketet validera, distribuera, köra och förstöra kommandon med Databricks CLI). Se Använda tjänstens huvudnamn för att autentisera med Azure Databricks.

  Kommentar

  Du kan inte ange ett hemligt Azure Databricks OAuth-värde i paketkonfigurationsfilen. Ange i stället den lokala miljövariabeln DATABRICKS_CLIENT_SECRET. Eller så kan du lägga till värdet i client_secret en konfigurationsprofil och sedan ange profilens namn med mappningen profile (eller genom att använda --profile alternativen eller -p när du kör paketet validera, distribuera, köra och förstöra kommandon med Databricks CLI).

• För Azure CLI-autentisering används mappningen azure_workspace_resource_id . Du kan också ange det här värdet i den lokala miljövariabeln DATABRICKS_AZURE_RESOURCE_ID. Eller så kan du skapa en konfigurationsprofil med azure_workspace_resource_id värdet och sedan ange profilens namn med mappningen profile (eller genom att använda --profile alternativen eller -p när du kör paketet validera, distribuera, köra och förstöra kommandon med Databricks CLI). Se Azure CLI-autentisering.

• För Azure-klienthemlig autentisering med tjänstens huvudnamn används mappningarna azure_workspace_resource_id, azure_tenant_idoch azure_client_id . Du kan också ange dessa värden i de lokala miljövariablerna DATABRICKS_AZURE_RESOURCE_ID, ARM_TENANT_IDrespektive , och ARM_CLIENT_ID. Eller så kan du skapa en konfigurationsprofil med azure_workspace_resource_idvärdena , azure_tenant_idoch azure_client_id och sedan ange profilens namn med mappningen profile (eller genom att använda --profile alternativen eller -p när du kör paketet validera, distribuera, köra och förstöra kommandon med Databricks CLI). Se Microsoft Entra ID-tjänstens huvudnamnsautentisering.

  Kommentar

  Du kan inte ange ett Azure-klienthemlighetsvärde i paketkonfigurationsfilen. Ange i stället den lokala miljövariabeln ARM_CLIENT_SECRET. Eller så kan du lägga till värdet i azure_client_secret en konfigurationsprofil och sedan ange profilens namn med mappningen profile (eller genom att använda --profile alternativen eller -p när du kör paketet validera, distribuera, köra och förstöra kommandon med Databricks CLI).

• För Azure-autentisering av hanterade identiteter används mappningarna azure_use_msi, azure_client_idoch azure_workspace_resource_id . Du kan också ange dessa värden i de lokala miljövariablerna ARM_USE_MSI, ARM_CLIENT_IDrespektive , och DATABRICKS_AZURE_RESOURCE_ID. Eller så kan du skapa en konfigurationsprofil med azure_use_msivärdena , azure_client_idoch azure_workspace_resource_id och sedan ange profilens namn med mappningen profile (eller genom att använda --profile alternativen eller -p när du kör paketet validera, distribuera, köra och förstöra kommandon med Databricks CLI). Se autentisering av hanterade Azure-identiteter.

• Mappningen azure_environment anger Azure-miljötypen (till exempel Public, UsGov, Kina och Tyskland) för en specifik uppsättning API-slutpunkter. Standardvärdet är PUBLIC. Du kan också ange det här värdet i den lokala miljövariabeln ARM_ENVIRONMENT. Eller så kan du lägga till värdet i azure_environment en konfigurationsprofil och sedan ange profilens namn med mappningen profile (eller genom att använda --profile alternativen eller -p när du kör paketet validera, distribuera, köra och förstöra kommandon med Databricks CLI).

• Mappningen azure_login_app_id är inte i drift och är reserverad för intern användning.

• Mappningen auth_type anger vilken Azure Databricks-autentiseringstyp som ska användas, särskilt i fall där Databricks CLI härleder en oväntad autentiseringstyp. Se fältet Autentiseringstyp.

Behörigheter

Mappningen på den översta nivån permissions anger en eller flera behörighetsnivåer som ska tillämpas på alla resurser som definierats i paketet. Om du vill använda behörigheter för en specifik resurs kan du läsa Definiera behörigheter för en specifik resurs.

Tillåtna behörighetsnivåer på den översta nivån är CAN_VIEW, CAN_MANAGEoch CAN_RUN.

I följande exempel i en paketkonfigurationsfil definieras behörighetsnivåer för en användare, grupp och tjänstens huvudnamn, som tillämpas på alla jobb, pipelines, experiment och modeller som definierats i resources paketet:

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

Artefakter

Mappningen på den översta nivån artifacts anger en eller flera artefakter som skapas automatiskt under paketdistributioner och kan användas senare i paketkörningar. Varje underordnad artefakt stöder följande mappningar:

• type måste anges. Om du vill skapa en Python-hjulfil innan du distribuerar måste den här mappningen vara inställd på whl.
• path är en valfri relativ sökväg från platsen för paketkonfigurationsfilen till platsen för Python-hjulfilens setup.py fil. Om path det inte ingår försöker Databricks CLI hitta Python-hjulfilens setup.py fil i paketets rot.
• files är en valfri mappning som innehåller en underordnad source mappning, som du kan använda för att ange icke-standardplatser som ska inkluderas för komplexa bygginstruktioner. Platser anges som relativa sökvägar från platsen för paketkonfigurationsfilen.
• build är en valfri uppsättning icke-standardversionskommandon som du vill köra lokalt före distributionen. För Python-hjulversioner förutsätter Databricks CLI att det kan hitta en lokal installation av Python-paketet wheel för att köra versioner och kör kommandot python setup.py bdist_wheel som standard under varje paketdistribution. Om du vill ange flera kompileringskommandon separerar du varje kommando med tecken med dubbel-ampersand (&&).

Mer information, inklusive ett exempelpaket som använder artifacts, finns i Utveckla en Python-hjulfil med databricks-tillgångspaket.

Dricks

Du kan definiera, kombinera och åsidosätta inställningarna för artefakter i paket med hjälp av de tekniker som beskrivs i Definiera artefaktinställningar dynamiskt i Databricks-tillgångspaket.

inbegripa

Matrisen include anger en lista över sökvägsglober som innehåller konfigurationsfiler som ska ingå i paketet. Dessa sökvägsglober är relativa till platsen för paketkonfigurationsfilen där sökvägens globs anges.

Databricks CLI inkluderar inte några konfigurationsfiler som standard i paketet. Du måste använda matrisen include för att ange alla konfigurationsfiler som ska ingå i paketet, förutom databricks.yml själva filen.

Den här include matrisen kan bara visas som en mappning på den översta nivån.

Följande exempel i en paketkonfigurationsfil innehåller de tre angivna konfigurationsfilerna. Dessa filer finns i samma katalog som paketkonfigurationsfilen:

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

Följande exempel i en paketkonfigurationsfil innehåller alla filer med filnamn som börjar med bundle och slutar med .yml. Dessa filer finns i samma katalog som paketkonfigurationsfilen:

include:
  - "bundle*.yml"

Resurser

Mappningen resources anger information om de Azure Databricks-resurser som används av paketet.

Den här resources mappningen kan visas som en mappning på den översta nivån, eller så kan den vara underordnad ett eller flera av målen i den översta målmappningen och innehåller noll eller en av de resurstyper som stöds. Varje resurstypmappning innehåller en eller flera enskilda resursdeklarationer, som var och en måste ha ett unikt namn. Dessa enskilda resursdeklarationer använder motsvarande objekts create-åtgärds nyttolast för begäran, uttryckt i YAML, för att definiera resursen. Egenskaper som stöds för en resurs är motsvarande objekts fält som stöds.

Nyttolaster för att skapa åtgärdsbegäran dokumenteras i referensen databricks bundle schema för Databricks REST API och kommandot matar ut alla objektscheman som stöds. Dessutom databricks bundle validate returnerar kommandot varningar om okända resursegenskaper finns i paketkonfigurationsfiler.

I följande tabell visas resurstyper som stöds för paket och länkar till dokumentation om motsvarande nyttolaster.

Resurstyp	Resursmappningar
jobs	Jobbmappningar: POST /api/2.1/jobs/create Mer information finns i jobbaktivitetstyper och åsidosätt nya jobbklusterinställningar.
pipelines	Pipelinemappningar: POST /api/2.0/pipelines
experiments	Experimentmappningar: POST /api/2.0/mlflow/experiments/create
models	Modellmappningar: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoints	Modell som betjänar slutpunktsmappningar: POST /api/2.0/serving-endpoints
registered_models (Unity Catalog)	Mappningar för Enhetskatalogmodell: POST /api/2.1/unity-catalog/models

Alla sökvägar till mappar och filer som refereras till av resursdeklarationer är relativa till platsen för paketkonfigurationsfilen där dessa sökvägar anges.

I följande exempel deklareras ett jobb med resursnyckeln hello-job och en pipeline med resursnyckeln hello-pipeline:

resources:
  jobs:
    hello-job:
      name: hello-job
      tasks:
        - task_key: hello-task
          existing_cluster_id: 1234-567890-abcde123
          notebook_task:
            notebook_path: ./hello.py
  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

synkronisering

Matrisen sync anger en lista över fil- eller sökvägsglober som ska inkluderas i paketdistributioner eller undantas från paketdistributioner, beroende på följande regler:

• Baserat på en lista över fil- och sökvägsglober i en .gitignore fil i paketets rot kan mappningen include innehålla en lista över filglober, sökvägsglober eller båda, i förhållande till paketets rot, som uttryckligen ska inkluderas.
• Baserat på en lista över fil- och sökvägsglober i en .gitignore fil i paketets rot, plus listan över fil- och sökvägsglober i mappningen include , exclude kan mappningen innehålla en lista över filglober, sökvägsglober eller båda, i förhållande till paketets rot, som uttryckligen ska undantas.

Alla sökvägar till angivna mappar och filer är relativa till platsen för paketkonfigurationsfilen där dessa sökvägar anges.

Syntaxen för include och exclude fil- och sökvägsmönster följer standardmönstersyntaxen .gitignore . Se gitignore-mönsterformat.

Om till exempel följande .gitignore fil innehåller följande poster:

.databricks
my_package/dist

Och paketkonfigurationsfilen innehåller följande include mappning:

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

Sedan ingår alla filer i my_package/dist mappen med filnamnstillägget *.whl . Andra filer i my_package/dist mappen ingår inte.

Men om paketkonfigurationsfilen också innehåller följande exclude mappning:

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

Sedan ingår alla filer i my_package/dist mappen med filnamnstillägget *.whl, förutom filen med namnet delete-me.whl. Andra filer i my_package/dist mappen ingår inte heller.

Matrisen sync kan också deklareras i mappningen targets för ett specifikt mål. Alla sync matriser som deklareras i ett mål sammanfogas med alla matrisdeklarationer på den översta nivån sync . Om du till exempel fortsätter med föregående exempel sammanfogas följande include mappning på targets nivån med mappningen include i matrisen på den översta nivån sync :

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

När du kör databricks bundle validate --output jsonär den relevanta delen av den resulterande grafen följande:

"sync": {
  "include": [
    "my_package/dist/*.whl",
    "my_package/dist/delete-me.whl"
  ],
  "exclude": [
    "my_package/dist/delete-me.whl"
  ]
}

Mål

Mappningen targets anger en eller flera kontexter där Azure Databricks-arbetsflöden ska köras. Varje mål är en unik samling artefakter, Azure Databricks-arbetsyteinställningar och Azure Databricks-jobb- eller pipelineinformation.

Den här targets mappningen är valfri men rekommenderas starkt. Om den anges kan den bara visas som en mappning på den översta nivån. Om mappningen targets inte har angetts används alltid inställningarna på den översta arbetsytan, artefakter och resursmappningar .

Mappningen targets består av en eller flera målmappningar, som var och en måste ha ett unikt programmatiskt (eller logiskt) namn.

Om en målmappning inte anger workspace, artifactseller resources underordnade mappningar använder det målet inställningarna på den översta nivån workspace, artifactsoch resources mappningar.

Om en målmappning anger en workspace, artifacts, eller resources mappning och en toppnivå workspace, artifactseller resources mappning också finns, åsidosätts eventuella motstridiga inställningar av inställningarna i målet.

Ett mål kan också åsidosätta värdena för alla variabler på den översta nivån.

Om du vill ange att ett mål är standardvärdet om inget annat anges lägger du till mappningen default och anger till true. Det här målet med namnet dev är till exempel standardmålet:

targets:
  dev:
    default: true

Om du vill ange att ett mål ska behandlas som ett utvecklingsmål lägger du till mappningen mode och anger till development. Om du vill ange att ett mål behandlas som produktionsmål lägger du till mappningen mode och anger till production. Det här målet med namnet prod behandlas till exempel som ett produktionsmål:

targets:
  prod:
    mode: production

Att mode ange innehåller en samling motsvarande standardbeteenden för förproduktions- och produktionsarbetsflöden. Mer information finns i Distributionslägen för Databricks Asset Bundle. Dessutom kan du ange run_as för varje mål, enligt beskrivningen i Ange en körningsidentitet för ett Databricks Asset Bundles-arbetsflöde.

I följande exempel deklareras två mål. Det första målet har ett programmatiskt (eller logiskt) namn på dev och är standardmålet. Det andra målet har ett programmatiskt (eller logiskt) namn på prod och är inte standardmålet. Det andra målet använder en Azure Databricks-anslutningsprofil med namnet PROD för autentisering:

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

Kör följande kommandon för att verifiera, distribuera och köra jobb eller pipelines inom dev målet:

# 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 <job-or-pipeline-programmatic-name>

# 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 <job-or-pipeline-programmatic-name>

Kör i stället följande kommandon för att verifiera, distribuera och köra det här jobbet inom prod målet:

# 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 <job-or-pipeline-programmatic-name>

Anpassade variabler

Du kan använda anpassade variabler för att göra paketkonfigurationsfilerna mer modulära och återanvändbara. Du kan till exempel deklarera en variabel som representerar ID:t för ett befintligt kluster och sedan vill ändra variabelns värde till olika kluster-ID:er för olika arbetsflödeskörningar inom flera mål utan att ändra paketkonfigurationsfilernas ursprungliga kod.

Anpassade variabler deklareras i paketkonfigurationsfilerna i mappningen variables . För varje variabel anger du en valfri beskrivning, standardvärde, typ eller uppslag för att hämta ett ID-värde med följande format:

variables:
  <variable-name>:
    description: <optional-description>
    default: <optional-default-value>
    type: <optional-type-value>
    lookup:
      <optional-object-type>: <optional-object-name>

Kommentar

Variabler antas vara av typen string, såvida inte type är inställt på complex. Se Definiera en komplex variabel.

Om du till exempel vill deklarera en variabel med namnet my_cluster_id med standardvärdet 1234-567890-abcde123, och en variabel med namnet my_notebook_path med standardvärdet ./hello.py:

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

Om du inte anger ett default värde för en variabel som en del av den här deklarationen måste du ange det när du kör paketkommandon, via en miljövariabel eller någon annanstans i paketkonfigurationsfilerna enligt beskrivningen i Ange en variabels värde.

Kommentar

Oavsett vilken metod du väljer att ange variabelvärden använder du samma metod under både distributions- och körningsstegen. Annars kan du få oväntade resultat mellan tidpunkten för en distribution och ett jobb eller en pipelinekörning som baseras på den befintliga distributionen.

Om du vill referera till dina anpassade variabler i paketkonfigurationsfilerna använder du ersättningar. För variabler använder du formatet ${var.<variable_name>}. Till exempel för att referera till variabler med namnet my_cluster_id och 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}

Ange en variabels värde

Om du inte har angett något default värde för en variabel, eller om du tillfälligt vill åsidosätta default värdet för en variabel, anger du variabelns nya temporära värde med någon av följande metoder:

• Ange variabelns värde som en del av ett bundle kommando, till exempel validate, deployeller run. Om du vill göra detta använder du alternativet --var="<key>=<value>", där <key> är variabelns namn och <value> är variabelns värde. Som en del av bundle validate kommandot kan du till exempel ange värdet 1234-567890-abcde123 för variabeln med namnet my_cluster_idoch ange värdet ./hello.py för variabeln med namnet my_notebook_path, kör:

  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"
  

• Ange variabelns värde genom att ange en miljövariabel. Miljövariabelns namn måste börja med BUNDLE_VAR_. Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet. Om du till exempel vill ange värdet 1234-567890-abcde123 för variabeln med namnet my_cluster_idoch ange värdet ./hello.py för variabeln med namnet my_notebook_pathkör du följande kommando innan du anropar ett bundle kommando som validate, deployeller run:

  För Linux och macOS:

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

  För Windows:

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

  Eller ange variabelns värde som en del av ett bundle kommando som validate, deployeller run, till exempel för Linux och macOS:

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

  Eller för Windows:

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

• Ange variabelns värde i paketkonfigurationsfilerna. Det gör du genom att använda en variables mappning i mappningen targets enligt det här formatet:

  variables:
    <variable-name>: <value>
  

  Om du till exempel vill ange värden för variablerna med namnet my_cluster_id och my_notebook_path för två separata mål:

  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
  

I föregående exempel letar Databricks CLI efter värden för variablerna my_cluster_id och my_notebook_path i följande ordning stoppar du när det hittar ett värde för varje matchande variabel och hoppar över andra platser för variabeln:

1. Inom alla --var alternativ som anges som en del av bundle kommandot.
2. I alla miljövariabler som börjar med BUNDLE_VAR_.
3. I alla variables mappningar, bland mappningarna targets i paketkonfigurationsfilerna.
4. Valfritt default värde för variabelns definition, bland de översta mappningarna variables i paketkonfigurationsfilerna.

Definiera en komplex variabel

Om du vill definiera en anpassad variabel med en komplex typ för ditt paket anger du type till complex i paketkonfigurationen.

Kommentar

Det enda giltiga värdet för inställningen type är complex. Dessutom misslyckas paketverifieringen om type har angetts till complex och den default definierade för variabeln är ett enda värde.

I följande exempel definieras klusterinställningar i en anpassad komplex variabel med namnet 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

Hämta ett objekts ID-värde

För objekttyperna alert, cluster_policy, cluster, instance_pooldashboard, job, metastore, pipeline, service_principalqueryoch warehouse kan du definiera en lookup för din anpassade variabel för att hämta ett namngivet objekts ID med det här formatet:

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

Om en sökning har definierats för en variabel används ID:t för objektet med det angivna namnet som värdet för variabeln. Detta säkerställer att rätt löst ID för objektet alltid används för variabeln.

Kommentar

Ett fel uppstår om ett objekt med det angivna namnet inte finns eller om det finns fler än ett objekt med det angivna namnet.

I följande konfiguration ${var.my_cluster_id} ersätts till exempel med ID:t för det delade klustret 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}

Substitutioner

Du kan använda ersättningar för att göra paketkonfigurationsfilerna mer modulära och återanvändbara.

Dricks

Du kan också använda dynamiska värdereferenser för jobbparametervärden för att skicka kontext om en jobbkörning till jobbaktiviteter. Se Skicka kontext om jobbkörningar till jobbaktiviteter.

När du till exempel kör bundle validate --output json kommandot kan du se ett diagram som det här (ellipserna anger utelämnat innehåll, för korthet):

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

I föregående exempel kan du referera till värdet someone@example.com i paketkonfigurationsfilen med ersättningen ${workspace.current_user.userName}.

På samma sätt ersätter följande:

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

I en paketkonfigurationsfil, till exempel följande (ellipsen anger utelämnat innehåll, för korthet):

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Skulle matcha till följande diagram när du kör bundle validate --output json kommandot (ellipserna anger utelämnat innehåll, för korthet):

{
  "bundle": {
    "name": "hello-bundle",
    "target": "dev",
    "...": "..."
  },
  "workspace": {
    "profile": "DEFAULT",
    "current_user": {
      "...": "...",
      "userName": "someone@example.com",
      "...": "...",
    },
    "root": "/Users/someone@example.com/.bundle/hello-bundle/my-envs/dev",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

Du kan också skapa ersättningar för namngivna resurser. Till exempel för pipelinen som konfigurerats med namnet my_pipeline, ${resources.pipelines.my_pipeline.target} är ersättningen för värdet för målet my_pipelineför .

För att fastställa giltiga ersättningar kan du använda schemahierarkin som beskrivs i REST API-referensen eller utdata från bundle schema kommandot.

Här är några vanliga ersättningar:

• ${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}