Delen via

Configuraties van Databricks Asset Bundle

  • Artikel

In dit artikel worden de syntaxis beschreven voor configuratiebestanden van Databricks Asset Bundle, die Databricks Asset Bundles definiëren. Zie Wat zijn Databricks-assetbundels?

Een bundelconfiguratiebestand moet worden uitgedrukt in YAML-indeling en moet minimaal de bundeltoewijzing op het hoogste niveau bevatten. Elke bundel moet minimaal één (en slechts één) bundelconfiguratiebestand met de naam databricks.ymlbevatten. Als er meerdere bundelconfiguratiebestanden zijn, moet naar het databricks.yml bestand worden verwezen met behulp van de include toewijzing.

Zie de officiële YAML-specificatie en zelfstudie voor meer informatie over YAML.

Als u bundelconfiguratiebestanden wilt maken en ermee wilt werken, raadpleegt u de ontwikkeling van Databricks Asset Bundles.

Overzicht

Deze sectie bevat een visuele weergave van het schema van het bundelconfiguratiebestand. Zie Toewijzingen voor meer informatie.

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

Voorbeelden

Notitie

Zie Voorbeelden van bundelconfiguraties en de opslagplaats met bundelvoorbeelden in GitHub voor configuratievoorbeelden waarin bundelfuncties en algemene gebruiksvoorbeelden voor bundels worden gedemonstreert.

In de volgende voorbeeldbundelconfiguratie wordt een lokaal bestand opgegeven hello.py dat zich in dezelfde map bevindt als dit lokale bundelconfiguratiebestand met de naam databricks.yml. Dit notebook wordt uitgevoerd als een taak met behulp van het externe cluster met de opgegeven cluster-id. De URL van de externe werkruimte en verificatiereferenties voor werkruimten worden gelezen uit het lokale configuratieprofiel van de beller met de naam DEFAULT.

Databricks raadt u aan om de host toewijzing te gebruiken in plaats van de default toewijzing waar mogelijk, omdat uw bundelconfiguratiebestanden hierdoor draagbaarder worden. Als u de host toewijzing instelt, krijgt de Databricks CLI de opdracht om een overeenkomend profiel in uw .databrickscfg bestand te vinden en vervolgens de velden van dat profiel te gebruiken om te bepalen welk Databricks-verificatietype moet worden gebruikt. Als er meerdere profielen met een overeenkomend host veld in uw .databrickscfg bestand bestaan, moet u de profile Databricks CLI instrueren over welk specifiek profiel u wilt gebruiken. Zie de prod doeldeclaratie verderop in deze sectie voor een voorbeeld.

Met deze techniek kunt u de taakdefinities en -instellingen in het resources blok opnieuw gebruiken en overschrijven:

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

Hoewel het volgende bundelconfiguratiebestand functioneel gelijkwaardig is, is het niet modulair, waardoor het niet goed hergebruik mogelijk is. Deze declaratie voegt ook een taak toe aan de taak in plaats van de bestaande taak te overschrijven:

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

In het volgende voorbeeld wordt een doel toegevoegd met de naam prod die gebruikmaakt van een andere EXTERNE werkruimte-URL en verificatiereferenties voor werkruimte, die worden gelezen uit de overeenkomende host vermelding van .databrickscfg het bestand van de beller met de opgegeven werkruimte-URL. Deze taak voert dezelfde notebook uit, maar gebruikt een ander extern cluster met de opgegeven cluster-id. U hoeft de toewijzing niet binnen de notebook_task prod toewijzing te declareren, omdat deze terugvalt om de notebook_task toewijzing binnen de toewijzing op het hoogste niveau resources te gebruiken, als de notebook_task toewijzing niet expliciet wordt overschreven binnen de prod toewijzing.

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

Deze taak valideren, implementeren en uitvoeren binnen het dev doel:

# 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

In plaats daarvan kunt u deze taak valideren, implementeren en uitvoeren binnen het prod doel:

# 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

Hieronder ziet u het vorige voorbeeld, maar splitst u op in onderdeelbestanden voor nog meer modularisatie en hergebruikt u meerdere bundelconfiguratiebestanden. Met deze techniek kunt u niet alleen verschillende definities en instellingen opnieuw gebruiken, maar u kunt ook een van deze bestanden wisselen met andere bestanden die volledig andere declaraties bieden:

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

Toewijzingen

In de volgende secties worden de syntaxis van het bundelconfiguratiebestand beschreven op basis van de toewijzing op het hoogste niveau.

bundel

Een configuratiebestand voor bundels mag slechts één toewijzing op het hoogste niveau bundle bevatten die de inhoud van de bundel en de instellingen van de Azure Databricks-werkruimte koppelt.

Deze bundle toewijzing moet een name toewijzing bevatten die een programmatische (of logische) naam voor de bundel aangeeft. In het volgende voorbeeld wordt een bundel met de programmatische (of logische) naam hello-bundledeclareren.

bundle:
  name: hello-bundle

Een bundle toewijzing kan ook een onderliggend element zijn van een of meer doelen in de toewijzing van doelen op het hoogste niveau. Elk van deze onderliggende bundle toewijzingen geeft eventuele niet-standaard onderdrukkingen op doelniveau op. De waarde van name de toewijzing op het hoogste niveau bundle kan echter niet worden overschreven op het doelniveau.

compute_id

De bundle toewijzing kan een onderliggende compute_id toewijzing hebben. Met deze toewijzing kunt u de id van een cluster opgeven die moet worden gebruikt als onderdrukking voor alle clusters die elders in het bundelconfiguratiebestand zijn gedefinieerd. Deze onderdrukking is bedoeld voor scenario's met alleen ontwikkeling vóór productie. De compute_id toewijzing werkt alleen voor het doel waarop de toewijzing is mode ingesteld.development Zie de toewijzing van doelen voor meer informatie over de compute_id toewijzing.

Git

U kunt details van Git-versiebeheer ophalen en overschrijven die aan uw bundel zijn gekoppeld. Dit is handig voor het toevoegen van aantekeningen aan uw geïmplementeerde resources. U wilt bijvoorbeeld de oorspronkelijke URL van uw opslagplaats opnemen in de beschrijving van een machine learning-model dat u implementeert.

Wanneer u een bundle opdracht uitvoert, zoals validate, deploy of run, wordt de bundle configuratiestructuur van de opdracht gevuld met de volgende standaardinstellingen:

  • bundle.git.origin_url, dat de oorspronkelijke URL van de opslagplaats vertegenwoordigt. Dit is dezelfde waarde die u zou krijgen als u de opdracht git config --get remote.origin.url uit uw gekloonde opslagplaats hebt uitgevoerd. U kunt vervangingen gebruiken om naar deze waarde te verwijzen met uw bundelconfiguratiebestanden, zoals ${bundle.git.origin_url}.
  • bundle.git.branch, dat de huidige vertakking in de opslagplaats vertegenwoordigt. Dit is dezelfde waarde die u zou krijgen als u de opdracht git branch --show-current uit uw gekloonde opslagplaats hebt uitgevoerd. U kunt vervangingen gebruiken om naar deze waarde te verwijzen met uw bundelconfiguratiebestanden, zoals ${bundle.git.branch}.
  • bundle.git.commit, dat de HEAD doorvoer in de opslagplaats vertegenwoordigt. Dit is dezelfde waarde die u zou krijgen als u de opdracht git rev-parse HEAD uit uw gekloonde opslagplaats hebt uitgevoerd. U kunt vervangingen gebruiken om naar deze waarde te verwijzen met uw bundelconfiguratiebestanden, zoals ${bundle.git.commit}.

Als u Git-instellingen wilt ophalen of overschrijven, moet uw bundel zich in een map bevinden die is gekoppeld aan een Git-opslagplaats, bijvoorbeeld een lokale map die wordt geïnitialiseerd door de opdracht uit te git clone voeren. Als de map niet is gekoppeld aan een Git-opslagplaats, zijn deze Git-instellingen leeg.

U kunt de origin_url en branch instellingen binnen de toewijzing van uw toewijzing op het git hoogste niveau bundle als volgt overschrijven:

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

databricks_cli_version

De bundle toewijzing kan een databricks_cli_version toewijzing bevatten die de Databricks CLI-versie beperkt die is vereist voor de bundel. Dit kan problemen voorkomen die worden veroorzaakt door het gebruik van toewijzingen die niet worden ondersteund in een bepaalde versie van de Databricks CLI.

De Databricks CLI-versie voldoet aan semantische versiebeheer en de databricks_cli_version toewijzing ondersteunt het opgeven van versiebeperkingen. Als de huidige databricks --version waarde zich niet binnen de grenzen bevindt die zijn opgegeven in de toewijzing van databricks_cli_version de bundel, treedt er een fout op wanneer databricks bundle validate deze wordt uitgevoerd op de bundel. In de volgende voorbeelden ziet u enkele algemene syntaxis voor versiebeperkingen:

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

Variabelen

Het bestand met bundelinstellingen kan één toewijzing op het hoogste niveau variables bevatten om variabele instellingen op te geven die moeten worden gebruikt. Zie Aangepaste variabelen.

Werkruimte

Het configuratiebestand voor bundels kan slechts één toewijzing op het hoogste niveau workspace bevatten om eventuele niet-standaardinstellingen voor Azure Databricks-werkruimten op te geven die moeten worden gebruikt.

root_path

Deze workspace toewijzing kan een root_path toewijzing bevatten om een niet-standaardhoofdpad op te geven dat in de werkruimte moet worden gebruikt voor implementaties en werkstroomuitvoeringen, bijvoorbeeld:

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

Voor de Databricks CLI wordt standaard root_path het standaardpad gebruikt, /Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}waarbij vervangingen worden gebruikt.

artifact_path

Deze workspace toewijzing kan ook een artifact_path toewijzing bevatten om een niet-standaardartefactpad op te geven dat in de werkruimte moet worden gebruikt voor implementaties en werkstroomuitvoeringen, bijvoorbeeld:

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

Voor de Databricks CLI wordt standaard artifact_path het standaardpad gebruikt, ${workspace.root}/artifactswaarbij vervangingen worden gebruikt.

Notitie

De artifact_path toewijzing biedt geen ondersteuning voor DBFS-paden (Databricks File System).

file_path

Deze workspace toewijzing kan ook een file_path toewijzing bevatten om een niet-standaardbestandspad op te geven dat in de werkruimte moet worden gebruikt voor implementaties en werkstroomuitvoeringen, bijvoorbeeld:

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

Voor de Databricks CLI wordt standaard file_path het standaardpad gebruikt, ${workspace.root}/fileswaarbij vervangingen worden gebruikt.

state_path

De state_path toewijzing wordt standaard ingesteld op het standaardpad van ${workspace.root}/state en vertegenwoordigt het pad in uw werkruimte om terraform-statusinformatie over implementaties op te slaan.

Andere werkruimtetoewijzingen

De workspace toewijzing kan ook de volgende optionele toewijzingen bevatten om het Azure Databricks-verificatiemechanisme op te geven dat moet worden gebruikt. Als ze niet zijn opgegeven binnen deze workspace toewijzing, moeten ze worden opgegeven in een workspace toewijzing als een onderliggend element van een of meer van de doelen in de toewijzing van doelen op het hoogste niveau.

Belangrijk

U moet codewaarden instellen voor de volgende workspace toewijzingen voor Azure Databricks-verificatie. U kunt bijvoorbeeld geen aangepaste variabelen opgeven voor de waarden van deze toewijzingen met behulp van de ${var.*} syntaxis.

  • De profile toewijzing (of de of -p opties --profile bij het uitvoeren van de bundel valideren, implementeren, uitvoeren en vernietigen van opdrachten met de Databricks CLI) geeft de naam op van een configuratieprofiel dat moet worden gebruikt met deze werkruimte voor Azure Databricks-verificatie. Dit configuratieprofiel wordt toegewezen aan het profiel dat u hebt gemaakt bij het instellen van de Databricks CLI.

    Notitie

    Databricks raadt u aan de host toewijzing te gebruiken (of de --profile of -p opties bij het uitvoeren van de bundelvalidatie, implementeren, uitvoeren en vernietigen van opdrachten met de Databricks CLI) in plaats van de profile toewijzing, omdat uw bundelconfiguratiebestanden hierdoor draagbaarder worden. Als u de host toewijzing instelt, krijgt de Databricks CLI de opdracht om een overeenkomend profiel in uw .databrickscfg bestand te vinden en vervolgens de velden van dat profiel te gebruiken om te bepalen welk Databricks-verificatietype moet worden gebruikt. Als er meerdere profielen met een overeenkomend host veld in uw .databrickscfg bestand bestaan, moet u de profile toewijzing (of de --profile -p opdrachtregelopties) gebruiken om de Databricks CLI te instrueren over welk profiel u wilt gebruiken. Zie de prod doeldeclaratie in de voorbeelden voor een voorbeeld.

  • De host toewijzing geeft de URL voor uw Azure Databricks-werkruimte op. Zie de URL per werkruimte.

  • Voor OAuth M2M-verificatie (machine-to-machine) wordt de toewijzing client_id gebruikt. U kunt deze waarde ook instellen in de lokale omgevingsvariabele DATABRICKS_CLIENT_ID. U kunt ook een configuratieprofiel maken met de client_id waarde en vervolgens de naam van het profiel opgeven met de profile toewijzing (of door de --profile of -p opties te gebruiken bij het uitvoeren van de bundelvalidatie, implementeren, uitvoeren en vernietigen van opdrachten met de Databricks CLI). Zie Een service-principal gebruiken om te verifiëren met Azure Databricks.

    Notitie

    U kunt geen Azure Databricks OAuth-geheime waarde opgeven in het configuratiebestand voor bundels. Stel in plaats daarvan de lokale omgevingsvariabele DATABRICKS_CLIENT_SECRETin. U kunt ook de client_secret waarde toevoegen aan een configuratieprofiel en vervolgens de naam van het profiel opgeven met de profile toewijzing (of met behulp van de --profile of -p opties bij het uitvoeren van de bundelvalidatie, implementeren, uitvoeren en vernietigen van opdrachten met de Databricks CLI).

  • Voor Azure CLI-verificatie wordt de toewijzing azure_workspace_resource_id gebruikt. U kunt deze waarde ook instellen in de lokale omgevingsvariabele DATABRICKS_AZURE_RESOURCE_ID. U kunt ook een configuratieprofiel maken met de azure_workspace_resource_id waarde en vervolgens de naam van het profiel opgeven met de profile toewijzing (of door de --profile of -p opties te gebruiken bij het uitvoeren van de bundelvalidatie, implementeren, uitvoeren en vernietigen van opdrachten met de Databricks CLI). Zie Azure CLI-verificatie.

  • Voor verificatie van azure-clientgeheimen met service-principals, de toewijzingen azure_workspace_resource_iden azure_tenant_idazure_client_id worden deze gebruikt. U kunt deze waarden ook instellen in de lokale omgevingsvariabelen DATABRICKS_AZURE_RESOURCE_IDen ARM_TENANT_IDARM_CLIENT_IDrespectievelijk. U kunt ook een configuratieprofiel maken met de azure_workspace_resource_id, en azure_tenant_idwaarden en azure_client_id vervolgens de naam van het profiel opgeven met de profile toewijzing (of met behulp van de --profile of -p opties bij het uitvoeren van de bundel valideren, implementeren, uitvoeren en vernietigen van opdrachten met de Databricks CLI). Zie Verificatie van de service-principal van Microsoft Entra ID.

    Notitie

    U kunt geen azure-clientgeheimwaarde opgeven in het configuratiebestand van de bundel. Stel in plaats daarvan de lokale omgevingsvariabele ARM_CLIENT_SECRETin. U kunt ook de azure_client_secret waarde toevoegen aan een configuratieprofiel en vervolgens de naam van het profiel opgeven met de profile toewijzing (of met behulp van de --profile of -p opties bij het uitvoeren van de bundelvalidatie, implementeren, uitvoeren en vernietigen van opdrachten met de Databricks CLI).

  • Voor verificatie van door Azure beheerde identiteiten worden de toewijzingen azure_use_msien azure_client_idazure_workspace_resource_id gebruikt. U kunt deze waarden ook instellen in de lokale omgevingsvariabelen ARM_USE_MSIen ARM_CLIENT_IDDATABRICKS_AZURE_RESOURCE_IDrespectievelijk. U kunt ook een configuratieprofiel maken met de azure_use_msi, en azure_client_idwaarden en azure_workspace_resource_id vervolgens de naam van het profiel opgeven met de profile toewijzing (of met behulp van de --profile of -p opties bij het uitvoeren van de bundel valideren, implementeren, uitvoeren en vernietigen van opdrachten met de Databricks CLI). Zie verificatie van door Azure beheerde identiteiten.

  • Met de azure_environment toewijzing wordt het Azure-omgevingstype (zoals Public, UsGov, China en Duitsland) opgegeven voor een specifieke set API-eindpunten. De standaardwaarde is PUBLIC. U kunt deze waarde ook instellen in de lokale omgevingsvariabele ARM_ENVIRONMENT. U kunt ook de azure_environment waarde toevoegen aan een configuratieprofiel en vervolgens de naam van het profiel opgeven met de profile toewijzing (of met behulp van de --profile of -p opties bij het uitvoeren van de bundelvalidatie, implementeren, uitvoeren en vernietigen van opdrachten met de Databricks CLI).

  • De azure_login_app_id toewijzing is niet operationeel en is gereserveerd voor intern gebruik.

  • Met auth_type de toewijzing wordt het verificatietype Azure Databricks opgegeven dat moet worden gebruikt, met name in gevallen waarin de Databricks CLI een onverwacht verificatietype afgeeft. Zie het veld Verificatietype.

Machtigingen

De toewijzing op het hoogste niveau permissions geeft een of meer machtigingsniveaus op die moeten worden toegepast op alle resources die in de bundel zijn gedefinieerd. Als u machtigingen wilt toepassen op een specifieke resource, raadpleegt u Machtigingen definiëren voor een specifieke resource.

Toegestane machtigingsniveaus op het hoogste niveau zijn CAN_VIEW, CAN_MANAGEen CAN_RUN.

In het volgende voorbeeld in een bundelconfiguratiebestand worden machtigingsniveaus gedefinieerd voor een gebruiker, groep en service-principal, die worden toegepast op alle taken, pijplijnen, experimenten en modellen die in resources de bundel zijn gedefinieerd:

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

Artefacten

Met de toewijzing op het hoogste niveau artifacts worden een of meer artefacten opgegeven die automatisch tijdens bundelimplementaties worden gebouwd en later in bundeluitvoeringen kunnen worden gebruikt. Elk onderliggend artefact ondersteunt de volgende toewijzingen:

  • type is vereist. Als u een Python-wielbestand wilt maken voordat u implementeert, moet deze toewijzing worden ingesteld op whl.
  • path is een optioneel, relatief pad van de locatie van het bundelconfiguratiebestand naar de locatie van het Bestand van het Python-wielbestand setup.py . Als path dit niet is inbegrepen, probeert de Databricks CLI het bestand van setup.py het Python-wielbestand te vinden in de hoofdmap van de bundel.
  • files is een optionele toewijzing die een onderliggende source toewijzing bevat, die u kunt gebruiken om niet-standaardlocaties op te geven die moeten worden opgenomen voor complexe build-instructies. Locaties worden opgegeven als relatieve paden vanaf de locatie van het bundelconfiguratiebestand.
  • build is een optionele set niet-standaard buildopdrachten die u lokaal wilt uitvoeren vóór de implementatie. Voor Python-wheel-builds gaat de Databricks CLI ervan uit dat het een lokale installatie van het Python-pakket wheel kan vinden om builds uit te voeren en dat de opdracht python setup.py bdist_wheel standaard wordt uitgevoerd tijdens elke bundelimplementatie. Als u meerdere buildopdrachten wilt opgeven, scheidt u elke opdracht met dubbele ampersand (&&) tekens.

Zie Een Python-wielbestand ontwikkelen met behulp van Databricks Asset Bundles voor meer informatie, waaronder een voorbeeldbundel die gebruikmaakt artifactsvan Een Python-wielbestand.

Tip

U kunt de instellingen voor artefacten in bundels definiëren, combineren en overschrijven met behulp van de technieken die worden beschreven in artefactinstellingen dynamisch definiëren in Databricks Asset Bundles.

bevatten

De include matrix geeft een lijst met padglobs die configuratiebestanden bevatten die in de bundel moeten worden opgenomen. Deze padglobs zijn relatief ten opzichte van de locatie van het bundelconfiguratiebestand waarin de padglobs worden opgegeven.

De Databricks CLI bevat standaard geen configuratiebestanden in de bundel. U moet de include matrix gebruiken om alle configuratiebestanden op te geven die moeten worden opgenomen in de bundel, behalve het databricks.yml bestand zelf.

Deze include matrix kan alleen worden weergegeven als een toewijzing op het hoogste niveau.

Het volgende voorbeeld in een bundelconfiguratiebestand bevat de drie opgegeven configuratiebestanden. Deze bestanden bevinden zich in dezelfde map als het bundelconfiguratiebestand:

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

Het volgende voorbeeld in een bundelconfiguratiebestand bevat alle bestanden met bestandsnamen die beginnen met bundle en eindigen met .yml. Deze bestanden bevinden zich in dezelfde map als het bundelconfiguratiebestand:

include:
  - "bundle*.yml"

weg

De resources toewijzing bevat informatie over de Azure Databricks-resources die door de bundel worden gebruikt.

Deze resources toewijzing kan worden weergegeven als een toewijzing op het hoogste niveau of kan een onderliggend element zijn van een of meer doelen in de toewijzing van doelen op het hoogste niveau en bevat nul of een van de ondersteunde resourcetypen. Elke toewijzing van resourcetypen bevat een of meer afzonderlijke resourcedeclaraties, die elk een unieke naam moeten hebben. Deze afzonderlijke resourcedeclaraties maken gebruik van de nettolading van de aanvraag van het bijbehorende object, uitgedrukt in YAML, om de resource te definiëren. Ondersteunde eigenschappen voor een resource zijn de ondersteunde velden van het bijbehorende object.

Nettoladingen voor bewerkingsaanvragen worden gedocumenteerd in de Databricks REST API-verwijzing en de databricks bundle schema opdracht voert alle ondersteunde objectschema's uit. Bovendien retourneert de databricks bundle validate opdracht waarschuwingen als onbekende resource-eigenschappen worden gevonden in bundelconfiguratiebestanden.

De volgende tabel bevat ondersteunde resourcetypen voor bundels en koppelingen naar documentatie over de bijbehorende nettoladingen.

Brontype Resourcetoewijzingen
jobs Taaktoewijzingen: POST /api/2.1/jobs/create

Zie taaktypen en overschrijf nieuwe taakclusterinstellingen voor meer informatie.
pipelines Pijplijntoewijzingen: POST /api/2.0/pipelines
experiments Experimenttoewijzingen: POST /api/2.0/mlflow/experiments/create
models Modeltoewijzingen: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoints Model voor eindpunttoewijzingen: POST /api/2.0/serving-endpoints
registered_models (Unity Catalog) Toewijzingen van Unity Catalog-modellen: POST /api/2.1/unity-catalog/models

Alle paden naar mappen en bestanden waarnaar wordt verwezen door resourcedeclaraties, zijn relatief ten opzichte van de locatie van het bundelconfiguratiebestand waarin deze paden worden opgegeven.

In het volgende voorbeeld wordt een taak met de resourcesleutel van hello-job en een pijplijn met de resourcesleutel van 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

Sync

Met de sync toewijzing wordt een lijst met bestands- of padglobs opgegeven die moeten worden opgenomen in bundelimplementaties of die moeten worden uitgesloten van bundelimplementaties, afhankelijk van de volgende regels:

  • Op basis van een lijst met bestands- en padglobs in een .gitignore bestand in de hoofdmap van de bundel kan de include toewijzing een lijst met bestandsglobs, padglobs of beide bevatten, ten opzichte van de hoofdmap van de bundel, om expliciet op te nemen.
  • Op basis van een lijst met bestands- en padglobs in een .gitignore bestand in de hoofdmap van de bundel, plus de lijst met bestands- en padglobs in de include toewijzing, kan de exclude toewijzing een lijst met bestandsglobs, padglobs of beide, ten opzichte van de hoofdmap van de bundel, bevatten om expliciet uit te sluiten.

Alle paden naar opgegeven mappen en bestanden zijn relatief ten opzichte van de locatie van het bundelconfiguratiebestand waarin deze paden worden opgegeven.

De syntaxis voor include en exclude bestands- en padpatronen volgen de standaardpatroonsyntaxis .gitignore . Zie gitignore Pattern Format.

Als het volgende .gitignore bestand bijvoorbeeld de volgende vermeldingen bevat:

.databricks
my_package/dist

Het configuratiebestand voor de bundel bevat de volgende include toewijzing:

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

Vervolgens worden alle bestanden in de my_package/dist map met de bestandsextensie *.whl opgenomen. Alle andere bestanden in de my_package/dist map zijn niet opgenomen.

Als het configuratiebestand van de bundel echter ook de volgende exclude toewijzing bevat:

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

Vervolgens worden alle bestanden in de my_package/dist map met een bestandsextensie van *.whl, behalve het bestand met de naam delete-me.whl, opgenomen. Alle andere bestanden in de my_package/dist map zijn ook niet opgenomen.

De sync toewijzing kan ook worden gedeclareerd in de targets toewijzing voor een specifiek doel. Elke sync toewijzing die in een doel is gedeclareerd, wordt samengevoegd met declaraties op het hoogste niveau sync . Als u bijvoorbeeld verdergaat met het voorgaande voorbeeld, wordt de volgende include toewijzing op niveau targets samengevoegd met de include toewijzing in de toewijzing op het hoogste niveau sync :

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

Wanneer u uitvoert databricks bundle validate --output json, is het relevante gedeelte van de resulterende grafiek als volgt:

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

Doelstellingen

De targets toewijzing geeft een of meer contexten op waarin Azure Databricks-werkstromen moeten worden uitgevoerd. Elk doel is een unieke verzameling artefacten, azure Databricks-werkruimte-instellingen en Azure Databricks-taak- of pijplijndetails.

Deze targets toewijzing is optioneel, maar wordt ten zeerste aanbevolen. Als deze is opgegeven, kan deze alleen worden weergegeven als een toewijzing op het hoogste niveau. Als de targets toewijzing niet is opgegeven, worden de instellingen in de werkruimte, artefacten en resourcetoewijzingen op het hoogste niveau altijd gebruikt.

De targets toewijzing bestaat uit een of meer doeltoewijzingen, die elk een unieke programmatische (of logische) naam moeten hebben.

Als een doeltoewijzing geen onderliggende toewijzingen opgeeft resources workspace, artifactsgebruikt dat doel de instellingen op het hoogste niveau workspaceartifactsen resources toewijzingen.

Als een doeltoewijzing een workspace, artifactsof resources toewijzing en een toewijzing op het hoogste niveauworkspaceartifacts, of resources toewijzing ook bevat, worden conflicterende instellingen overschreven door de instellingen binnen het doel.

Een doel kan ook de waarden van variabelen op het hoogste niveau overschrijven.

Als u wilt opgeven dat een doel de standaard is, tenzij anders opgegeven, voegt u de default toewijzing toe, ingesteld op true. Dit doel met de naam dev is bijvoorbeeld het standaarddoel:

targets:
  dev:
    default: true

Als u wilt opgeven dat een doel wordt behandeld als een ontwikkelingsdoel, voegt u de mode toewijzing toe, ingesteld op development. Als u wilt opgeven dat een doel wordt behandeld als productiedoel, voegt u de mode toewijzing toe, ingesteld op production. Dit doel met de naam prod wordt bijvoorbeeld behandeld als een productiedoel:

targets:
  prod:
    mode: production

mode Opgeven biedt een verzameling van overeenkomend standaardgedrag voor preproductie- en productiewerkstromen. Zie de implementatiemodi voor Databricks Asset Bundle voor meer informatie. Daarnaast kunt u voor elk doel opgeven, zoals beschreven in Een uitvoeringsidentiteit opgeven run_as voor een Databricks Asset Bundles-werkstroom.

In het volgende voorbeeld worden twee doelen declareren. Het eerste doel heeft een programmatische (of logische) naam van dev en is het standaarddoel. Het tweede doel heeft een programmatische (of logische) naam van prod en is niet het standaarddoel. Dit tweede doel maakt gebruik van een Azure Databricks-verbindingsprofiel met de naam PROD verificatie:

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

Voer de volgende opdrachten uit om taken of pijplijnen binnen het dev doel te valideren, implementeren en uitvoeren:

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

Voer in plaats daarvan de volgende opdrachten uit om deze taak in het prod doel te valideren, te implementeren en uit te voeren:

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

Aangepaste variabelen

U kunt aangepaste variabelen gebruiken om uw bundelconfiguratiebestanden modulairer en herbruikbaarder te maken. U kunt bijvoorbeeld een variabele declareren die de id van een bestaand cluster vertegenwoordigt en vervolgens de waarde van die variabele wilt wijzigen in verschillende cluster-id's voor verschillende werkstroomuitvoeringen binnen meerdere doelen zonder de oorspronkelijke code van uw bundelconfiguratiebestanden te wijzigen.

Aangepaste variabelen worden gedeclareerd in uw bundelconfiguratiebestanden binnen de variables toewijzing. Stel voor elke variabele een optionele beschrijving, standaardwaarde, type of zoekactie in om een id-waarde op te halen met behulp van de volgende indeling:

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

Notitie

Variabelen worden ervan uitgegaan dat ze van het type stringzijn, tenzij type deze is ingesteld op complex. Zie Een complexe variabele definiëren.

Als u bijvoorbeeld een variabele my_cluster_id wilt declareren met de standaardwaarde van 1234-567890-abcde123, en een variabele my_notebook_path met de standaardwaarde van ./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

Als u geen waarde opgeeft default voor een variabele als onderdeel van deze declaratie, moet u deze instellen bij het uitvoeren van bundelopdrachten, via een omgevingsvariabele of elders in uw bundelconfiguratiebestanden, zoals beschreven in de waarde van een variabele instellen.

Notitie

Welke methode u ook kiest om variabele waarden op te geven, gebruik dezelfde benadering tijdens zowel de implementatie- als de uitvoeringsfase. Anders krijgt u mogelijk onverwachte resultaten tussen de tijd van een implementatie en een taak of pijplijnuitvoering die is gebaseerd op die bestaande implementatie.

Als u wilt verwijzen naar uw aangepaste variabelen in uw bundelconfiguratiebestanden, gebruikt u vervangingen. Voor variabelen gebruikt u de notatie ${var.<variable_name>}. Bijvoorbeeld om te verwijzen naar variabelen met de naam my_cluster_id en 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}

De waarde van een variabele instellen

Als u geen waarde hebt opgegeven default voor een variabele of als u de default waarde voor een variabele tijdelijk wilt overschrijven, geeft u de nieuwe tijdelijke waarde van de variabele op met behulp van een van de volgende methoden:

  • Geef de waarde van de variabele op als onderdeel van een bundle opdracht, zoals validate, deployof run. Hiervoor gebruikt u de optie --var="<key>=<value>", waar <key> de naam van de variabele staat en <value> de waarde van de variabele. Als u bijvoorbeeld als onderdeel van de bundle validate opdracht de waarde van 1234-567890-abcde123 de variabele met de naam my_cluster_idwilt opgeven en de waarde wilt opgeven van ./hello.py de variabele met de naam my_notebook_path, voert u het volgende uit:

    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"

  • Geef de waarde van de variabele op door een omgevingsvariabele in te stellen. De naam van de omgevingsvariabele moet beginnen met BUNDLE_VAR_. Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem. Als u bijvoorbeeld de waarde van 1234-567890-abcde123 de variabele met de naam my_cluster_idwilt opgeven en de waarde wilt opgeven van ./hello.py de variabele met de naam my_notebook_path, voert u de volgende opdracht uit voordat u een bundle opdracht aanroept, zoals validate, deployof run:

    Voor Linux en macOS:

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

    Voor Windows:

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

    Of geef de waarde van de variabele op als onderdeel van een bundle opdracht, zoals validate, deployof runbijvoorbeeld voor Linux en macOS:

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

    Of voor Windows:

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

  • Geef de waarde van de variabele op in uw bundelconfiguratiebestanden. Gebruik hiervoor een variables toewijzing binnen de targets toewijzing, volgens deze indeling:

    variables:
  <variable-name>: <value>

    Als u bijvoorbeeld waarden wilt opgeven voor de variabelen met de naam my_cluster_id en my_notebook_path voor twee afzonderlijke doelen:

    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

In de voorgaande voorbeelden zoekt de Databricks CLI naar waarden voor de variabelen my_cluster_id en my_notebook_path wordt in de volgende volgorde gestopt wanneer er een waarde wordt gevonden voor elke overeenkomende variabele, waarbij alle andere locaties voor die variabele worden overgeslagen:

  1. Binnen alle --var opties die zijn opgegeven als onderdeel van de bundle opdracht.
  2. Binnen elke omgevingsvariabelenset die beginnen met BUNDLE_VAR_.
  3. Binnen alle variables toewijzingen, tussen de targets toewijzingen binnen uw bundelconfiguratiebestanden.
  4. Elke default waarde voor de definitie van die variabele, onder de toewijzingen op het hoogste niveau variables in uw bundelconfiguratiebestanden.

Een complexe variabele definiëren

Als u een aangepaste variabele met een complex type voor uw bundel wilt definiëren, stelt u deze in type complex de bundelconfiguratie in.

Notitie

De enige geldige waarde voor de type instelling is complex. Bovendien mislukt de bundelvalidatie als type deze is ingesteld complex op en de default gedefinieerde waarde voor de variabele één waarde is.

In het volgende voorbeeld worden clusterinstellingen gedefinieerd binnen een aangepaste complexe variabele met de naam 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

De id-waarde van een object ophalen

Voor de alertobjecttypen , dashboardcluster_policyclusterinstance_pool, job, metastorequerypipelineen service_principalwarehouse objecttypen kunt u een lookup voor uw aangepaste variabele definiëren om de id van een benoemd object op te halen met behulp van deze indeling:

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

Als een zoekactie is gedefinieerd voor een variabele, wordt de id van het object met de opgegeven naam gebruikt als de waarde van de variabele. Dit zorgt ervoor dat de juiste opgeloste id van het object altijd wordt gebruikt voor de variabele.

Notitie

Er treedt een fout op als een object met de opgegeven naam niet bestaat of als er meer dan één object is met de opgegeven naam.

In de volgende configuratie ${var.my_cluster_id} wordt bijvoorbeeld vervangen door de id van het gedeelde cluster 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}

Vervangingen

U kunt vervangingen gebruiken om uw bundelconfiguratiebestanden modulairer en herbruikbaarder te maken.

Tip

U kunt ook dynamische waardeverwijzingen gebruiken voor taakparameterwaarden om context door te geven over een taakuitvoering aan taaktaken. Zie Pass-context over taakuitvoeringen in taaktaken.

Wanneer u bijvoorbeeld de bundle validate --output json opdracht uitvoert, ziet u mogelijk een grafiek zoals deze (de weglatingstekens geven aan dat de inhoud wordt weggelaten, voor de beknoptheid):

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

In het voorgaande voorbeeld kunt u verwijzen naar de waarde someone@example.com in uw bundelconfiguratiebestand met de vervanging ${workspace.current_user.userName}.

Op dezelfde manier worden de volgende vervangingen vervangen:

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

In een bundelconfiguratiebestand zoals het volgende (met het beletselteken wordt de weggelaten inhoud aangegeven, ter beknoptheid):

bundle:
  name: hello-bundle

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

# ...

targets:
  dev:
    default: true

Dit wordt omgezet in de volgende grafiek wanneer u de bundle validate --output json opdracht uitvoert (de weglatingstekens geven aan dat de inhoud wordt weggelaten, ter beknoptheid):

{
  "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",
    "...": "..."
  },
  "...": {
    "...": "..."
  }
}

U kunt ook vervangingen voor benoemde resources maken. Bijvoorbeeld, voor de pijplijn die is geconfigureerd met de naam my_pipeline, ${resources.pipelines.my_pipeline.target} is de vervanging voor de waarde van het doel van my_pipeline.

Als u geldige vervangingen wilt bepalen, kunt u de schemahiërarchie gebruiken die wordt beschreven in de REST API-verwijzing of de uitvoer van de bundle schema opdracht.

Hier volgen enkele veelgebruikte vervangingen:

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