Delen via

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

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

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

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

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

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

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

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

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

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

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

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.

cluster_id

De bundle toewijzing kan een onderliggende cluster_id toewijzing hebben. Met deze toewijzing kunt u de id van een cluster opgeven die moet worden gebruikt als onderdrukking voor clusters die elders in het bundelconfiguratiebestand zijn gedefinieerd. Zie Cluster-URL en -id voor informatie over het ophalen van de id van een cluster.

De cluster_id onderdrukking is bedoeld voor scenario's met alleen ontwikkeling en wordt alleen ondersteund voor het doel waarop mode de toewijzing is ingesteld development. Zie doelen voor meer informatie over de target toewijzing.

compute_id

Notitie

Deze instelling is afgeschaft. Gebruik in plaats daarvan cluster_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 clusters die elders in het bundelconfiguratiebestand zijn gedefinieerd.

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 instellingenbestand voor bundels kan één toewijzing op het hoogste niveau variables bevatten waarbij aangepaste variabelen worden gedefinieerd. Stel voor elke variabele een optionele beschrijving, standaardwaarde in, of de aangepaste variabele een complex type is of zoekactie om een id-waarde op te halen, met behulp van de volgende indeling:

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

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 wilt verwijzen naar een aangepaste variabele in de bundelconfiguratie, gebruikt u de vervanging ${var.<variable_name>}.

Zie Vervangingen en variabelen in Databricks Asset Bundles voor meer informatie over aangepaste variabelen en vervangingen.

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.

Belangrijk

Geldige Databricks-werkruimtepaden beginnen met of /Workspace /Volumes. Aangepaste werkruimtepaden worden automatisch voorafgegaan door /Workspace, dus als u een vervanging van het werkruimtepad in uw aangepaste pad gebruikt, zoals ${workspace.file_path}, hoeft u niet vooraf te gaan /Workspace aan het pad.

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: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/my-envs/${bundle.target}

Voor de Databricks CLI wordt standaard root_path het standaardpad gebruikt, /Workspace/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: /Workspace/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: /Workspace/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 Toegang tot Azure Databricks verifiëren met een service-principal met behulp van OAuth (OAuth M2M).

    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 MS Entra-service-principal.

    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 de verificatietoegang tot Azure Databricks-resources.

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.

De volgende voorbeeldconfiguratie bevat drie configuratiebestanden. Deze bestanden bevinden zich in dezelfde map als het bundelconfiguratiebestand:

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

De volgende voorbeeldconfiguratie 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
cluster Clustertoewijzingen: POST /api/2.1/clusters/create
dashboard Dashboardtoewijzingen: POST /api/2.0/lakeview/dashboards
experiment Experimenttoewijzingen: POST /api/2.0/mlflow/experiments/create
baan Taaktoewijzingen: POST /api/2.1/jobs/create

Zie taaktypen en overschrijf nieuwe taakclusterinstellingen voor meer informatie.
pijpleiding Pijplijntoewijzingen: POST /api/2.0/pipelines
model Modeltoewijzingen: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint Model voor eindpunttoewijzingen: POST /api/2.0/serving-endpoints
registered_model (Unity Catalog) Toewijzingen van Unity Catalog-modellen: POST /api/2.1/unity-catalog/models
schema (Unity Catalog) Schematoewijzingen voor Unity Catalog: POST /api/2.1/unity-catalog/schema's

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.

cluster

Met de clusterresource kunt u clusters voor alle doeleinden maken. In het volgende voorbeeld wordt een cluster gemaakt met de naam my_cluster en wordt ingesteld dat als het cluster wordt gebruikt om het notebook uit te voeren in my_job:

bundle:
  name: clusters

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

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

Dashboard

Met de dashboardresource kunt u AI/BI-dashboards in een bundel beheren. Zie Dashboards voor informatie over AI/BI-dashboards.

Het volgende voorbeeld bevat en implementeert het voorbeelddashboard van NYC Taxi Trip Analysis naar de Databricks-werkruimte.

resources:
  dashboards:
    nyc_taxi_trip_analysis:
      display_name: "NYC Taxi Trip Analysis"
      file_path: ../src/nyc_taxi_trip_analysis.lvdash.json
      warehouse_id: ${var.warehouse_id}

Als u de gebruikersinterface gebruikt om het dashboard te wijzigen, worden wijzigingen die via de gebruikersinterface zijn aangebracht, niet toegepast op het JSON-dashboardbestand in de lokale bundel, tenzij u het expliciet bijwerkt met behulp van bundle generate. U kunt de --watch optie gebruiken om voortdurend wijzigingen in het dashboard te peilen en op te halen. Zie Een bundelconfiguratiebestand genereren.

Als u bovendien probeert een bundel te implementeren die een JSON-dashboardbestand bevat dat anders is dan het bestand in de externe werkruimte, treedt er een fout op. Gebruik --force de optie om het dashboard in de externe werkruimte af te dwingen en te overschrijven met de lokale werkruimte. Zie Een bundel implementeren.

taak

In het volgende voorbeeld wordt een taak met de resourcesleutel van hello-job:

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

pijpleiding

In het volgende voorbeeld wordt een pijplijn met de resourcesleutel van hello-pipeline:

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

schema

Met het schemaresourcetype kunt u Unity Catalog-schema's definiëren voor tabellen en andere assets in uw werkstromen en pijplijnen die zijn gemaakt als onderdeel van een bundel. Een schema, afgezien van andere resourcetypen, heeft de volgende beperkingen:

  • De eigenaar van een schemaresource is altijd de implementatiegebruiker en kan niet worden gewijzigd. Als run_as deze is opgegeven in de bundel, wordt deze genegeerd door bewerkingen in het schema.
  • Alleen velden die worden ondersteund door de bijbehorende API voor het maken van schema's-objecten, zijn beschikbaar voor de schema resource. Wordt bijvoorbeeld niet ondersteund omdat enable_predictive_optimization deze alleen beschikbaar is in de update-API.

In het volgende voorbeeld wordt een pijplijn met de resourcesleutel my_pipeline declareren waarmee een Unity Catalog-schema wordt gemaakt met de sleutel my_schema als doel:

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

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

Een toewijzing van subsidies op het hoogste niveau wordt niet ondersteund door Databricks Asset Bundles. Als u subsidies voor een schema wilt instellen, definieert u de subsidies voor het schema binnen de schemas toewijzing:

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

Sync

Met de sync toewijzing kunt u configureren welke bestanden deel uitmaken van uw bundelimplementaties.

opnemen en uitsluiten

De include en exclude toewijzingen binnen de sync toewijzing specificeren een lijst met bestanden of mappen die moeten worden opgenomen in, of 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 bestanden en mappen zijn relatief ten opzichte van de locatie van het bundelconfiguratiebestand waarin ze zijn 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

Paden

De sync toewijzing kan een paths toewijzing bevatten waarmee lokale paden worden opgegeven die moeten worden gesynchroniseerd met de werkruimte. Met de paths toewijzing kunt u algemene bestanden delen tussen bundels en kunt u bestanden synchroniseren die zich buiten de hoofdmap van de bundel bevinden. (De hoofdmap van de bundel is de locatie van het databricks.yml-bestand.) Dit is vooral handig wanneer u één opslagplaats hebt die als host fungeert voor meerdere bundels en bibliotheken, codebestanden of configuratie wilt delen.

Opgegeven paden moeten relatief zijn ten opzichte van bestanden en mappen die zijn verankerd in de map waarin de paths toewijzing is ingesteld. Als een of meer padwaarden de map doorkruisen naar een bovenliggend element van de hoofdmap van de bundel, wordt het hoofdpad dynamisch bepaald om ervoor te zorgen dat de mapstructuur intact blijft. Als de hoofdmap van de bundel bijvoorbeeld de naam my_bundle heeft, synchroniseert deze configuratie databricks.yml de common map die zich één niveau boven de hoofdmap van de bundel bevindt en de hoofdmap van de bundel zelf:

sync:
  paths:
    - ../common
    - .

Een implementatie van deze bundel resulteert in de volgende mapstructuur in de werkruimte:

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

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.

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

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.

De instellingen in de werkruimte, artefacten en resourcetoewijzingen op het hoogste niveau worden gebruikt als ze niet zijn opgegeven in een targets toewijzing, maar conflicterende instellingen worden overschreven door de instellingen binnen een doel.

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

default

Als u een doelstandaard wilt opgeven voor bundelopdrachten, stelt u de default toewijzing in op true. Dit doel met de naam dev is bijvoorbeeld het standaarddoel:

targets:
  dev:
    default: true

Als een standaarddoel niet is geconfigureerd of als u taken of pijplijnen binnen een specifiek doel wilt valideren, implementeren en uitvoeren, gebruikt u de -t optie van de bundelopdrachten.

De volgende opdrachten valideren, implementeren en uitvoeren my_job binnen de dev en prod doelen:

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

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

In het volgende voorbeeld worden twee doelen declareren. Het eerste doel heeft de naam dev en is het standaarddoel dat wordt gebruikt wanneer er geen doel is opgegeven voor bundelopdrachten. Het tweede doel heeft de naam prod en wordt alleen gebruikt wanneer dit doel is opgegeven voor bundelopdrachten.

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

modus en voorinstellingen

Om eenvoudige ontwikkel- en CI/CD-best practices mogelijk te maken, biedt Databricks Asset Bundles implementatiemodi voor doelen die standaardgedrag instellen voor preproductie- en productiewerkstromen. Sommige gedragingen kunnen ook worden geconfigureerd. Zie de implementatiemodi voor Databricks Asset Bundle voor meer informatie.

Tip

Als u uitvoeringsidentiteiten voor bundels wilt instellen, kunt u opgeven voor elk doel, zoals beschreven in Een uitvoeringsidentiteit opgeven run_as voor een Databricks Asset Bundles-werkstroom.

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

targets:
  prod:
    mode: production

U kunt enkele van de gedragingen aanpassen met behulp van de presets toewijzing. Zie Aangepaste voorinstellingen voor een lijst met beschikbare voorinstellingen. In het volgende voorbeeld ziet u een aangepast productiedoel waarmee alle productiebronnen worden voorafgegaan en gelabeld:

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

Als beide mode en presets zijn ingesteld, overschrijven vooraf ingestelde instellingen het standaardgedrag van de modus. Instellingen van afzonderlijke resources overschrijven de voorinstellingen. Als een planning bijvoorbeeld is ingesteld op UNPAUSED, maar de trigger_pause_status voorinstelling is ingesteld PAUSEDop , wordt het schema niet meer gebruikt.