Konfiguracja pakietu zasobów usługi Databricks

W tym artykule opisano składnię plików konfiguracji pakietu zasobów usługi Databricks, które definiują pakiety zasobów usługi Databricks. Zobacz Co to są pakiety zasobów usługi Databricks?

Plik konfiguracji pakietu musi być wyrażony w formacie YAML i musi zawierać co najmniej mapowanie pakietów najwyższego poziomu. Każdy pakiet musi zawierać co najmniej jeden (i tylko jeden) plik konfiguracji pakietu o nazwie databricks.yml. Jeśli istnieje wiele plików konfiguracji pakietu, należy się do nich odwoływać przy databricks.yml użyciu include mapowania.

Aby uzyskać więcej informacji na temat języka YAML, zobacz oficjalną specyfikację YAML i samouczek.

Aby utworzyć pliki konfiguracji pakietu i pracować z plikami konfiguracji, zobacz Programowanie pakietów zasobów usługi Databricks.

Omówienie

Ta sekcja zawiera wizualną reprezentację schematu pliku konfiguracji pakietu. Aby uzyskać szczegółowe informacje, zobacz Mapowania.

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

Przykłady

Uwaga

Przykłady konfiguracji, które demonstrują funkcje pakietu i typowe przypadki użycia pakietów, zobacz Przykłady konfiguracji pakietu i repozytorium przykładów pakietów w usłudze GitHub.

Poniższa przykładowa konfiguracja pakietu określa plik lokalny o nazwie hello.py , który znajduje się w tym samym katalogu co ten lokalny plik konfiguracji pakietu o nazwie databricks.yml. Ten notes jest uruchamiany jako zadanie przy użyciu klastra zdalnego z określonym identyfikatorem klastra. Poświadczenia uwierzytelniania zdalnego obszaru roboczego i adresu URL obszaru roboczego są odczytywane z lokalnego profilu konfiguracji obiektu wywołującego o nazwie DEFAULT.

Usługa Databricks zaleca użycie host mapowania zamiast default mapowania wszędzie tam, gdzie jest to możliwe, ponieważ sprawia to, że pliki konfiguracji pakietu są bardziej przenośne. host Ustawienie mapowania powoduje, że interfejs wiersza polecenia usługi Databricks znajdzie pasujący profil w .databrickscfg pliku, a następnie użyj pól tego profilu, aby określić typ uwierzytelniania usługi Databricks do użycia. Jeśli w pliku istnieje .databrickscfg wiele profilów z pasującym host polem, musisz użyć profile polecenia , aby poinstruować interfejs wiersza polecenia usługi Databricks o określonym profilu do użycia. Aby zapoznać się z przykładem, zobacz deklarację docelową prod w dalszej części tej sekcji.

Ta technika umożliwia ponowne użycie oraz zastąpienie definicji i ustawień zadania w resources bloku:

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

Chociaż następujący plik konfiguracji pakietu jest funkcjonalnie równoważny, nie jest modularyzowany, co nie umożliwia dobrego ponownego użycia. Ponadto ta deklaracja dołącza zadanie do zadania, a nie zastępuje istniejącego zadania:

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

Poniższy przykład dodaje element docelowy o nazwieprod, która używa innego adresu URL zdalnego obszaru roboczego i poświadczeń uwierzytelniania obszaru roboczego, które są odczytywane z pasującego host wpisu pliku obiektu wywołującego .databrickscfg z określonym adresem URL obszaru roboczego. To zadanie uruchamia ten sam notes, ale używa innego klastra zdalnego z określonym identyfikatorem klastra. Zwróć uwagę, że nie trzeba deklarować notebook_task mapowania w ramach prod mapowania, ponieważ wraca do używania notebook_task mapowania w ramach mapowania najwyższego poziomu resources , jeśli notebook_task mapowanie nie jest jawnie zastępowane w ramach prod mapowania.

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

Aby zweryfikować, wdrożyć i uruchomić to zadanie w ramach dev elementu docelowego:

# 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

Aby zweryfikować, wdrożyć i uruchomić to zadanie w ramach prod elementu docelowego:

# 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

Poniżej przedstawiono poprzedni przykład, ale podzielony na pliki składników w celu jeszcze większej modularyzacji i lepszego ponownego użycia w wielu plikach konfiguracji pakietu. Ta technika umożliwia nie tylko ponowne używanie różnych definicji i ustawień, ale także zamianę dowolnego z tych plików z innymi plikami, które zapewniają zupełnie inne deklaracje:

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

Mapowania

W poniższych sekcjach opisano składnię pliku konfiguracji pakietu według mapowania najwyższego poziomu.

• pakiet
• Zmiennych
• obszar roboczy
• permissions
• Artefakty
• include
• zasoby
• synchronizować
• Cele

pakiet

Plik konfiguracji pakietu musi zawierać tylko jedno mapowanie najwyższego poziomu bundle , które kojarzy zawartość pakietu i ustawienia obszaru roboczego usługi Azure Databricks.

To bundle mapowanie musi zawierać name mapowanie określające nazwę programową (lub logiczną) pakietu. Poniższy przykład deklaruje pakiet z nazwą hello-bundleprogramową (lub logiczną).

bundle:
  name: hello-bundle

bundle Mapowanie może być również elementem podrzędnym jednego lub większej liczby obiektów docelowych w mapowaniu obiektów docelowych najwyższego poziomu. Każde z tych mapowań podrzędnych bundle określa wszelkie przesłonięcia inne niż domyślne na poziomie docelowym. Jednak wartości mapowania name najwyższego poziomu bundle nie można zastąpić na poziomie docelowym.

cluster_id

Mapowanie bundle może mieć mapowanie podrzędne cluster_id . To mapowanie umożliwia określenie identyfikatora klastra do użycia jako przesłonięcia dla klastrów zdefiniowanych gdzie indziej w pliku konfiguracji pakietu. Aby uzyskać informacje na temat pobierania identyfikatora klastra, zobacz Adres URL i identyfikator klastra.

Zastąpienie cluster_id jest przeznaczone tylko dla scenariuszy przeznaczonych tylko do programowania i jest obsługiwane tylko dla obiektu docelowego, który ma jego mode mapowanie ustawione na wartość development. Aby uzyskać więcej informacji na temat target mapowania, zobacz cele.

compute_id

Uwaga

To ustawienie jest przestarzałe. Zamiast tego użyj cluster_id .

Mapowanie bundle może mieć mapowanie podrzędne compute_id . To mapowanie umożliwia określenie identyfikatora klastra do użycia jako przesłonięcia dla klastrów zdefiniowanych gdzie indziej w pliku konfiguracji pakietu.

Git

Możesz pobrać i zastąpić szczegóły kontroli wersji usługi Git skojarzone z pakietem. Jest to przydatne w przypadku dodawania adnotacji do wdrożonych zasobów. Możesz na przykład uwzględnić adres URL pochodzenia repozytorium w opisie wdrażanego modelu uczenia maszynowego.

Za każdym razem, gdy uruchamiasz bundle polecenie, takie jak validate, deploy lub run, bundle polecenie wypełnia drzewo konfiguracji polecenia następującymi ustawieniami domyślnymi:

• bundle.git.origin_url, który reprezentuje adres URL pochodzenia repozytorium. Jest to ta sama wartość, którą można uzyskać po uruchomieniu polecenia git config --get remote.origin.url z sklonowanego repozytorium. Za pomocą podstawiania można odwoływać się do tej wartości z plikami konfiguracji pakietu jako ${bundle.git.origin_url}.
• bundle.git.branch, który reprezentuje bieżącą gałąź w repozytorium. Jest to ta sama wartość, którą można uzyskać po uruchomieniu polecenia git branch --show-current z sklonowanego repozytorium. Za pomocą podstawiania można odwoływać się do tej wartości z plikami konfiguracji pakietu jako ${bundle.git.branch}.
• bundle.git.commit, który reprezentuje HEAD zatwierdzenie w repozytorium. Jest to ta sama wartość, którą można uzyskać po uruchomieniu polecenia git rev-parse HEAD z sklonowanego repozytorium. Za pomocą podstawiania można odwoływać się do tej wartości z plikami konfiguracji pakietu jako ${bundle.git.commit}.

Aby pobrać lub zastąpić ustawienia usługi Git, pakiet musi znajdować się w katalogu skojarzonym z repozytorium Git, na przykład katalogiem lokalnym zainicjowanym przez uruchomienie git clone polecenia . Jeśli katalog nie jest skojarzony z repozytorium Git, te ustawienia usługi Git są puste.

W razie potrzeby można zastąpić origin_url ustawienia i branch w git mapowaniu mapowania najwyższego poziomu bundle w następujący sposób:

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

databricks_cli_version

Mapowanie bundle może zawierać databricks_cli_version mapowanie, które ogranicza wersję interfejsu wiersza polecenia usługi Databricks wymaganą przez pakiet. Może to zapobiec problemom spowodowanym użyciem mapowań, które nie są obsługiwane w określonej wersji interfejsu wiersza polecenia usługi Databricks.

Wersja interfejsu wiersza polecenia usługi Databricks jest zgodna z semantyczną wersją , a databricks_cli_version mapowanie obsługuje określanie ograniczeń wersji. Jeśli bieżąca databricks --version wartość nie znajduje się w granicach określonych w mapowaniu pakietu databricks_cli_version , wystąpi błąd podczas databricks bundle validate wykonywania w pakiecie. W poniższych przykładach pokazano niektóre typowe składnie ograniczeń wersji:

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

Zmiennych

Plik ustawień pakietów może zawierać jedno mapowanie najwyższego poziomu variables , w którym zdefiniowano zmienne niestandardowe. Dla każdej zmiennej ustaw opcjonalny opis, wartość domyślną, niezależnie od tego, czy zmienna niestandardowa jest typem złożonym, czy wyszukiwaniem w celu pobrania wartości identyfikatora przy użyciu następującego formatu:

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>

Uwaga

Przyjmuje się, że zmienne mają być typu string, chyba że type ustawiono wartość complex. Zobacz Definiowanie zmiennej złożonej.

Aby odwołać się do zmiennej niestandardowej w ramach konfiguracji pakietu, użyj podstawienia ${var.<variable_name>}.

Aby uzyskać więcej informacji na temat zmiennych niestandardowych i podstawień, zobacz Podstawianie i zmienne w pakietach zasobów usługi Databricks.

obszar roboczy

Plik konfiguracji pakietu może zawierać tylko jedno mapowanie najwyższego poziomu workspace , aby określić domyślne ustawienia obszaru roboczego usługi Azure Databricks do użycia.

Ważne

Prawidłowe ścieżki obszaru roboczego usługi Databricks zaczynają się od /Workspace lub /Volumes. Niestandardowe ścieżki obszaru roboczego są automatycznie poprzedzone prefiksem /Workspace, więc jeśli używasz podstawianie ścieżki obszaru roboczego w ścieżce niestandardowej, takiej jak ${workspace.file_path}, nie musisz poprzedzać /Workspace ścieżki.

root_path

To workspace mapowanie może zawierać mapowanie, root_path aby określić inną niż domyślną ścieżkę główną do użycia w obszarze roboczym dla wdrożeń i przebiegów przepływu pracy, na przykład:

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

Domyślnie w interfejsie root_path wiersza polecenia usługi Databricks jest używana domyślna ścieżka /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}, która używa podstawień.

artifact_path

To workspace mapowanie może również zawierać mapowanie, aby określić inną niż domyślną artifact_path ścieżkę artefaktu do użycia w obszarze roboczym dla wdrożeń i przebiegów przepływu pracy, na przykład:

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

Domyślnie w interfejsie artifact_path wiersza polecenia usługi Databricks jest używana domyślna ścieżka ${workspace.root}/artifacts, która używa podstawień.

Uwaga

Mapowanie artifact_path nie obsługuje ścieżek systemu plików usługi Databricks (DBFS).

file_path

To workspace mapowanie może również zawierać mapowanie, aby określić inną niż domyślną file_path ścieżkę pliku do użycia w obszarze roboczym dla wdrożeń i przebiegów przepływu pracy, na przykład:

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

Domyślnie w interfejsie file_path wiersza polecenia usługi Databricks jest używana domyślna ścieżka ${workspace.root}/files, która używa podstawień.

state_path

Mapowanie state_path jest domyślnie ustawione na domyślną ścieżkę ${workspace.root}/state i reprezentuje ścieżkę w obszarze roboczym, aby przechowywać informacje o stanie programu Terraform dotyczące wdrożeń.

Inne mapowania obszarów roboczych

Mapowanie workspace może również zawierać następujące opcjonalne mapowania, aby określić mechanizm uwierzytelniania usługi Azure Databricks do użycia. Jeśli nie są one określone w tym workspace mapowaniu, muszą być określone w workspace mapowaniu jako element podrzędny co najmniej jednego miejsca docelowego w mapowaniu obiektów docelowych najwyższego poziomu.

Ważne

Musisz trwale kodować wartości dla następujących workspace mapowań uwierzytelniania usługi Azure Databricks. Na przykład nie można określić zmiennych niestandardowych dla wartości tych mapowań przy użyciu ${var.*} składni.

• Mapowanie profile (lub opcje lub --profile -p podczas uruchamiania pakietu walidować, wdrażać, uruchamiać i niszczyć polecenia za pomocą interfejsu wiersza polecenia usługi Databricks) określa nazwę profilu konfiguracji do użycia z tym obszarem roboczym na potrzeby uwierzytelniania usługi Azure Databricks. Ten profil konfiguracji jest mapowy na ten, który został utworzony podczas konfigurowania interfejsu wiersza polecenia usługi Databricks.

  Uwaga

  Usługa Databricks zaleca użycie host mapowania (lub --profile -p opcji podczas uruchamiania pakietu walidowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą interfejsu wiersza polecenia usługi Databricks) zamiast profile mapowania, ponieważ sprawia to, że pliki konfiguracji pakietu są bardziej przenośne. host Ustawienie mapowania powoduje, że interfejs wiersza polecenia usługi Databricks znajdzie pasujący profil w .databrickscfg pliku, a następnie użyj pól tego profilu, aby określić typ uwierzytelniania usługi Databricks do użycia. Jeśli w pliku istnieje .databrickscfg wiele profilów z pasującym host polem, musisz użyć profile mapowania (lub --profile -p opcji wiersza polecenia), aby poinstruować interfejs wiersza polecenia usługi Databricks o tym, którego profilu użyć. Przykład można znaleźć w prod deklaracji docelowej w przykładach.

• Mapowanie host określa adres URL obszaru roboczego usługi Azure Databricks. Zobacz Adres URL obszaru roboczego.

• W przypadku uwierzytelniania maszyny-maszyny (M2M) protokołu OAuth jest używane mapowanie client_id . Alternatywnie można ustawić tę wartość w lokalnej zmiennej środowiskowej DATABRICKS_CLIENT_ID. Możesz też utworzyć profil konfiguracji z client_id wartością, a następnie określić nazwę profilu z profile mapowaniem (lub za pomocą opcji lub -p podczas uruchamiania pakietu weryfikujące, wdrażać, uruchamiać i niszczyć polecenia za pomocą --profile interfejsu wiersza polecenia usługi Databricks). Zobacz Uwierzytelnianie dostępu do usługi Azure Databricks przy użyciu jednostki usługi przy użyciu protokołu OAuth (OAuth M2M).

  Uwaga

  Nie można określić wartości wpisu tajnego OAuth usługi Azure Databricks w pliku konfiguracji pakietu. Zamiast tego ustaw lokalną zmienną środowiskową DATABRICKS_CLIENT_SECRET. Możesz też dodać client_secret wartość do profilu konfiguracji, a następnie określić nazwę profilu z profile mapowaniem (lub za pomocą opcji lub -p podczas uruchamiania pakietu weryfikowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą --profile interfejsu wiersza polecenia usługi Databricks).

• W przypadku uwierzytelniania interfejsu wiersza polecenia platformy Azure jest używane mapowanie azure_workspace_resource_id . Alternatywnie można ustawić tę wartość w lokalnej zmiennej środowiskowej DATABRICKS_AZURE_RESOURCE_ID. Możesz też utworzyć profil konfiguracji z azure_workspace_resource_id wartością, a następnie określić nazwę profilu z profile mapowaniem (lub za pomocą opcji lub -p podczas uruchamiania pakietu weryfikujące, wdrażać, uruchamiać i niszczyć polecenia za pomocą --profile interfejsu wiersza polecenia usługi Databricks). Zobacz Uwierzytelnianie interfejsu wiersza polecenia platformy Azure.

• W przypadku uwierzytelniania wpisów tajnych klienta platformy Azure z jednostkami usługi są używane mapowania azure_workspace_resource_id, azure_tenant_idi azure_client_id . Alternatywnie można ustawić te wartości w lokalnych zmiennych DATABRICKS_AZURE_RESOURCE_IDśrodowiskowych , ARM_TENANT_IDi ARM_CLIENT_ID, odpowiednio. Możesz też utworzyć profil konfiguracji z wartościami azure_workspace_resource_id, azure_tenant_idi , a azure_client_id następnie określić nazwę profilu za profile pomocą mapowania (lub za pomocą opcji lub -p podczas uruchamiania pakietu weryfikujące, wdrażać, uruchamiać i niszczyć polecenia za pomocą --profile interfejsu wiersza polecenia usługi Databricks). Zobacz Uwierzytelnianie jednostki usługi MS Entra.

  Uwaga

  Nie można określić wartości wpisu tajnego klienta platformy Azure w pliku konfiguracji pakietu. Zamiast tego ustaw lokalną zmienną środowiskową ARM_CLIENT_SECRET. Możesz też dodać azure_client_secret wartość do profilu konfiguracji, a następnie określić nazwę profilu z profile mapowaniem (lub za pomocą opcji lub -p podczas uruchamiania pakietu weryfikowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą --profile interfejsu wiersza polecenia usługi Databricks).

• W przypadku uwierzytelniania tożsamości zarządzanych platformy azure_use_msiAzure używane są mapowania , azure_client_idi azure_workspace_resource_id . Alternatywnie można ustawić te wartości w lokalnych zmiennych ARM_USE_MSIśrodowiskowych , ARM_CLIENT_IDi DATABRICKS_AZURE_RESOURCE_ID, odpowiednio. Możesz też utworzyć profil konfiguracji z wartościami azure_use_msi, azure_client_idi , a azure_workspace_resource_id następnie określić nazwę profilu za profile pomocą mapowania (lub za pomocą opcji lub -p podczas uruchamiania pakietu weryfikujące, wdrażać, uruchamiać i niszczyć polecenia za pomocą --profile interfejsu wiersza polecenia usługi Databricks). Zobacz Uwierzytelnianie tożsamości zarządzanych platformy Azure.

• Mapowanie azure_environment określa typ środowiska platformy Azure (na przykład Publiczny, UsGov, Chiny i Niemcy) dla określonego zestawu punktów końcowych interfejsu API. Domyślna wartość to PUBLIC. Alternatywnie można ustawić tę wartość w lokalnej zmiennej środowiskowej ARM_ENVIRONMENT. Możesz też dodać azure_environment wartość do profilu konfiguracji, a następnie określić nazwę profilu z profile mapowaniem (lub za pomocą opcji lub -p podczas uruchamiania pakietu weryfikowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą --profile interfejsu wiersza polecenia usługi Databricks).

• Mapowanie azure_login_app_id nie działa i jest zarezerwowane do użytku wewnętrznego.

• Mapowanie auth_type określa typ uwierzytelniania usługi Azure Databricks do użycia, zwłaszcza w przypadkach, gdy interfejs wiersza polecenia usługi Databricks wnioskowa nieoczekiwany typ uwierzytelniania. Zobacz Uwierzytelnianie dostępu do zasobów usługi Azure Databricks.

Uprawnienia

Mapowanie najwyższego poziomu permissions określa co najmniej jeden poziom uprawnień, który ma być stosowany do wszystkich zasobów zdefiniowanych w pakiecie. Jeśli chcesz zastosować uprawnienia do określonego zasobu, zobacz Definiowanie uprawnień dla określonego zasobu.

Dozwolone poziomy uprawnień najwyższego poziomu to CAN_VIEW, CAN_MANAGEi CAN_RUN.

Poniższy przykład w pliku konfiguracji pakietu definiuje poziomy uprawnień dla użytkownika, grupy i jednostki usługi, które są stosowane do wszystkich zadań, potoków, eksperymentów i modeli zdefiniowanych w resources pakiecie:

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

Artefakty

Mapowanie najwyższego poziomu artifacts określa co najmniej jeden artefakt, który jest automatycznie kompilowany podczas wdrożeń pakietu i może być używany w kolejnych uruchomieniach pakietu. Każdy artefakt podrzędny obsługuje następujące mapowania:

• Ciąg type jest wymagany. Aby skompilować plik wheel języka Python przed wdrożeniem, to mapowanie musi być ustawione na whl.
• path jest opcjonalną ścieżką względną z lokalizacji pliku konfiguracji pakietu do lokalizacji pliku wheel języka setup.py Python. Jeśli path nie zostanie uwzględniona, interfejs wiersza polecenia usługi Databricks podejmie próbę znalezienia pliku setup.py wheel języka Python w katalogu głównym pakietu.
• files to opcjonalne mapowanie, które zawiera mapowanie podrzędne source , którego można użyć do określenia lokalizacji innych niż domyślne, które mają być uwzględniane w przypadku złożonych instrukcji kompilacji. Lokalizacje są określane jako ścieżki względne z lokalizacji pliku konfiguracji pakietu.
• build jest opcjonalnym zestawem poleceń kompilacji innych niż domyślne, które mają być uruchamiane lokalnie przed wdrożeniem. W przypadku kompilacji wheel języka Python interfejs wiersza polecenia usługi Databricks zakłada, że może znaleźć lokalną instalację pakietu języka Python wheel do uruchamiania kompilacji i uruchamia python setup.py bdist_wheel polecenie domyślnie podczas każdego wdrożenia pakietu. Aby określić wiele poleceń kompilacji, należy oddzielić każde polecenie podwójnymi znakami i (&&).

Aby uzyskać więcej informacji, w tym przykładowy pakiet korzystający z artifactsprogramu , zobacz Develop a Python wheel file using Databricks Asset Bundles (Tworzenie pliku wheel języka Python przy użyciu pakietów zasobów usługi Databricks).

Napiwek

Ustawienia artefaktów w pakietach można definiować, łączyć i zastępować przy użyciu technik opisanych w artykule Definiowanie ustawień artefaktów dynamicznie w pakietach zasobów usługi Databricks.

zawierać

Tablica include określa listę ścieżek globs, które zawierają pliki konfiguracji do uwzględnienia w pakiecie. Te globy ścieżki są względem lokalizacji pliku konfiguracji pakietu, w którym określono globy ścieżki.

Interfejs wiersza polecenia usługi Databricks domyślnie nie zawiera żadnych plików konfiguracji w pakiecie. Należy użyć tablicy include , aby określić dowolne i wszystkie pliki konfiguracji do uwzględnienia w pakiecie, innym niż databricks.yml sam plik.

Ta include tablica może być wyświetlana tylko jako mapowanie najwyższego poziomu.

Poniższa przykładowa konfiguracja obejmuje trzy pliki konfiguracji. Te pliki znajdują się w tym samym folderze co plik konfiguracji pakietu:

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

Poniższa przykładowa konfiguracja obejmuje wszystkie pliki z nazwami plików rozpoczynającymi się od i kończącymi się bundle na .yml. Te pliki znajdują się w tym samym folderze co plik konfiguracji pakietu:

include:
  - "bundle*.yml"

zasoby

Mapowanie resources określa informacje o zasobach usługi Azure Databricks używanych przez pakiet.

To resources mapowanie może być wyświetlane jako mapowanie najwyższego poziomu lub może być elementem podrzędnym jednego lub większej liczby obiektów docelowych w mapowaniu obiektów docelowych najwyższego poziomu i zawiera zero lub jeden z obsługiwanych typów zasobów. Każde mapowanie typu zasobu zawiera co najmniej jedną pojedynczą deklarację zasobów, która musi mieć unikatową nazwę. Te indywidualne deklaracje zasobów używają ładunku żądania operacji tworzenia odpowiadającego obiektu wyrażonego w yaML, aby zdefiniować zasób. Obsługiwane właściwości zasobu to obsługiwane pola odpowiedniego obiektu.

Ładunki żądań operacji tworzenia są udokumentowane w dokumentacji interfejsu API REST usługi Databricks, a databricks bundle schema polecenie zwraca wszystkie obsługiwane schematy obiektów. Ponadto polecenie zwraca ostrzeżenia, databricks bundle validate jeśli w plikach konfiguracji pakietu znajdują się nieznane właściwości zasobu.

W poniższej tabeli wymieniono obsługiwane typy zasobów dla pakietów i linki do dokumentacji dotyczącej odpowiednich ładunków.

Typ zasobu	Mapowania zasobów
klaster	Mapowania klastrów: POST /api/2.1/clusters/create
deska rozdzielcza	Mapowania pulpitów nawigacyjnych: POST /api/2.0/lakeview/dashboards
eksperyment	Mapowania eksperymentów: POST /api/2.0/mlflow/experiments/create
zadanie	Mapowania zadań: POST /api/2.1/jobs/create Aby uzyskać dodatkowe informacje, zobacz typy zadań zadań i zastąpić nowe ustawienia klastra zadań.
rurociąg	Mapowania potoków: POST /api/2.0/pipelines
model	Mapowania modeli: POST /api/2.0/mlflow/registered-models/create
model_serving_endpoint	Mapowania punktów końcowych obsługujące model: POST /api/2.0/serving-endpoints
registered_model (wykaz aparatu Unity)	Mapowania modeli wykazu aparatu Unity: POST /api/2.1/unity-catalog/models
schema (Wykaz aparatu Unity)	Mapowania schematów wykazu aparatu Unity: POST /api/2.1/unity-catalog/schemas

Wszystkie ścieżki do folderów i plików, do których odwołują się deklaracje zasobów, są powiązane z lokalizacją pliku konfiguracji pakietu, w którym określono te ścieżki.

cluster

Zasób klastra umożliwia tworzenie klastrów ogólnego przeznaczenia. Poniższy przykład tworzy klaster o nazwie my_cluster i ustawia go jako klaster do uruchomienia notesu w my_jobprogramie :

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"

pulpit nawigacyjny

Zasób pulpitu nawigacyjnego umożliwia zarządzanie pulpitami nawigacyjnymi AI/BI w pakiecie. Aby uzyskać informacje na temat pulpitów nawigacyjnych sztucznej inteligencji/analizy biznesowej, zobacz Pulpity nawigacyjne.

Poniższy przykład obejmuje i wdraża przykładowy pulpit nawigacyjny analizy taksówek w Nowym Jorku w obszarze roboczym usługi Databricks.

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}

Jeśli używasz interfejsu użytkownika do modyfikowania pulpitu nawigacyjnego, modyfikacje wprowadzone za pośrednictwem interfejsu użytkownika nie są stosowane do pliku JSON pulpitu nawigacyjnego w pakiecie lokalnym, chyba że jawnie zaktualizujesz go przy użyciu polecenia bundle generate. Możesz użyć --watch opcji , aby stale sondować i pobierać zmiany na pulpicie nawigacyjnym. Zobacz Generowanie pliku konfiguracji pakietu.

Ponadto w przypadku próby wdrożenia pakietu zawierającego plik JSON pulpitu nawigacyjnego, który różni się od tego w zdalnym obszarze roboczym, wystąpi błąd. Aby wymusić wdrożenie i zastąpienie pulpitu nawigacyjnego w zdalnym obszarze roboczym przy użyciu lokalnego, użyj --force opcji . Zobacz Wdrażanie pakietu.

zadanie

Poniższy przykład deklaruje zadanie z kluczem zasobu :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

rurociąg

Poniższy przykład deklaruje potok z kluczem hello-pipelinezasobu :

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

Typ zasobu schematu umożliwia zdefiniowanie schematów wykazu aparatu Unity dla tabel i innych zasobów w przepływach pracy i potokach utworzonych w ramach pakietu. Schemat, inny niż inne typy zasobów, ma następujące ograniczenia:

• Właściciel zasobu schematu jest zawsze użytkownikiem wdrożenia i nie można go zmienić. Jeśli run_as zostanie określony w pakiecie, zostanie on zignorowany przez operacje w schemacie.
• Dla zasobu są dostępne schema tylko pola obsługiwane przez odpowiedni interfejs API tworzenia obiektu Schematy. Na przykład nie jest obsługiwana, enable_predictive_optimization ponieważ jest dostępna tylko w interfejsie API aktualizacji.

W poniższym przykładzie zadeklarowany jest potok z kluczem my_pipeline zasobu, który tworzy schemat wykazu aparatu Unity z kluczem my_schema jako elementem docelowym:

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.

Mapowanie dotacji najwyższego poziomu nie jest obsługiwane przez pakiety zasobów usługi Databricks, więc jeśli chcesz ustawić dotacje dla schematu, zdefiniuj dotacje dla schematu schemas w ramach mapowania:

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"

synchronizować

Mapowanie sync umożliwia skonfigurowanie plików będących częścią wdrożeń pakietu.

dołączanie i wykluczanie

Mapowania include i exclude w ramach sync mapowania określają listę plików lub folderów do uwzględnienia w ramach lub wykluczenia z wdrożeń pakietów, w zależności od następujących reguł:

• Na podstawie dowolnej listy plików i ścieżek globs w .gitignore pliku głównym pakietu include mapowanie może zawierać listę globów plików, globów ścieżek lub obu elementów w stosunku do katalogu głównego pakietu, aby jawnie dołączyć.
• Na podstawie dowolnej listy plików i ścieżek globs w .gitignore pliku w katalogu głównym pakietu oraz listy globów plików i ścieżek w include mapowaniu exclude mapowanie mapowanie może zawierać listę globów plików, globów ścieżki lub obu elementów w stosunku do katalogu głównego pakietu, aby jawnie wykluczyć.

Wszystkie ścieżki do określonych plików i folderów są powiązane z lokalizacją pliku konfiguracji pakietu, w którym są określone.

Składnia wzorców plików include i exclude ścieżek są zgodne ze standardową .gitignore składnią wzorca. Zobacz format wzorca gitignore.

Jeśli na przykład następujący .gitignore plik zawiera następujące wpisy:

.databricks
my_package/dist

Plik konfiguracji pakietu zawiera następujące include mapowanie:

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

Następnie uwzględniane są wszystkie pliki w my_package/dist folderze z rozszerzeniem *.whl pliku. Żadne inne pliki w folderze my_package/dist nie są uwzględniane.

Jeśli jednak plik konfiguracji pakietu zawiera również następujące exclude mapowanie:

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

Następnie wszystkie pliki w folderze my_package/dist z rozszerzeniem *.whlpliku , z wyjątkiem pliku o nazwie delete-me.whl, są uwzględniane. Wszystkie inne pliki w folderze my_package/dist również nie są uwzględniane.

Mapowanie sync można również zadeklarować w targets mapowaniu dla określonego celu. Każde sync mapowanie zadeklarowane w obiekcie docelowym jest scalane z dowolnymi deklaracjami mapowania najwyższego poziomu sync . Na przykład kontynuując poprzedni przykład, następujące include mapowanie na targets poziomie scala się z include mapowaniem na najwyższym poziomie sync :

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

Ścieżki

Mapowanie sync może zawierać paths mapowanie określające ścieżki lokalne do synchronizacji z obszarem roboczym. Mapowanie paths umożliwia udostępnianie wspólnych plików w pakietach i może służyć do synchronizowania plików znajdujących się poza katalogem głównym pakietu. (Katalog główny pakietu jest lokalizacją pliku databricks.yml). Jest to szczególnie przydatne, gdy masz jedno repozytorium, które hostuje wiele pakietów i chce udostępniać biblioteki, pliki kodu lub konfigurację.

Określone ścieżki muszą być względem plików i katalogów zakotwiczonych w folderze, w którym paths ustawiono mapowanie. Jeśli co najmniej jedna wartość ścieżki przechodzi przez katalog do przodka katalogu głównego pakietu, ścieżka główna jest dynamicznie określana w celu zapewnienia, że struktura folderów pozostanie nienaruszona. Jeśli na przykład folder główny pakietu ma nazwę my_bundle , ta konfiguracja jest synchronizowana common z databricks.yml folderem znajdującym się na jednym poziomie powyżej katalogu głównego pakietu i samym katalogem głównym pakietu:

sync:
  paths:
    - ../common
    - .

Wdrożenie tego pakietu powoduje następującą strukturę folderów w obszarze roboczym:

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

Cele

Mapowanie targets określa co najmniej jeden kontekst, w którym mają być uruchamiane przepływy pracy usługi Azure Databricks. Każdy element docelowy to unikatowa kolekcja artefaktów, ustawień obszaru roboczego usługi Azure Databricks oraz szczegółów zadania lub potoku usługi Azure Databricks.

Mapowanie targets składa się z co najmniej jednego mapowania docelowego, które musi mieć unikatową nazwę programową (lub logiczną).

To targets mapowanie jest opcjonalne, ale zdecydowanie zalecane. Jeśli zostanie określony, może być wyświetlany tylko jako mapowanie najwyższego poziomu.

Ustawienia w obszarze roboczym najwyższego poziomu, artefakty i mapowania zasobów są używane, jeśli nie zostały określone w targets mapowaniu, ale wszystkie ustawienia powodujące konflikt są zastępowane przez ustawienia w obiekcie docelowym.

Obiekt docelowy może również zastąpić wartości dowolnych zmiennych najwyższego poziomu.

domyślna

Aby określić domyślną wartość docelową dla poleceń pakietu, ustaw default mapowanie na true. Na przykład ten obiekt docelowy o nazwie dev jest domyślnym obiektem docelowym:

targets:
  dev:
    default: true

Jeśli domyślny element docelowy nie jest skonfigurowany lub chcesz zweryfikować, wdrożyć i uruchomić zadania lub potoki w określonym obiekcie docelowym, użyj -t opcji poleceń pakietu.

Następujące polecenia weryfikują, wdrażają i uruchamiają w my_job obiektach dev docelowych i prod :

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

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

W poniższym przykładzie zadeklarowane są dwa cele. Pierwszy element docelowy ma nazwę dev i jest domyślnym elementem docelowym używanym, gdy dla poleceń pakietu nie określono żadnego elementu docelowego. Drugi element docelowy ma nazwę prod i jest używany tylko wtedy, gdy ten element docelowy jest określony dla poleceń pakietu.

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

tryb i ustawienia wstępne

Aby ułatwić opracowywanie i najlepsze rozwiązania dotyczące ciągłej integracji/ciągłego wdrażania, pakiety zasobów usługi Databricks udostępniają tryby wdrażania dla celów, które ustawiają domyślne zachowania dla przepływów pracy przedprodukcyjnej i produkcyjnej. Niektóre zachowania można również konfigurować. Aby uzyskać szczegółowe informacje, zobacz Tryby wdrażania pakietu zasobów usługi Databricks.

Napiwek

Aby ustawić tożsamości uruchamiania dla pakietów, można określić run_as dla każdego obiektu docelowego, zgodnie z opisem w temacie Określanie tożsamości przebiegu dla przepływu pracy pakietów zasobów usługi Databricks.

Aby określić, że element docelowy jest traktowany jako element docelowy programowania, dodaj mode mapowanie ustawione na development. Aby określić, że element docelowy jest traktowany jako docelowy w środowisku produkcyjnym, dodaj mode mapowanie ustawione na production. Na przykład ten obiekt docelowy o nazwie prod jest traktowany jako docelowy produkt produkcyjny:

targets:
  prod:
    mode: production

Niektóre zachowania można dostosować przy użyciu presets mapowania. Aby uzyskać listę dostępnych ustawień wstępnych, zobacz Niestandardowe ustawienia wstępne. W poniższym przykładzie przedstawiono dostosowany docelowy obiekt produkcyjny, który prefiksy i tagi wszystkich zasobów produkcyjnych:

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

W przypadku ustawienia i mode presets ustawienia ustawienia wstępne zastępują zachowanie trybu domyślnego. Ustawienia poszczególnych zasobów zastępują ustawienia wstępne. Jeśli na przykład harmonogram jest ustawiony na UNPAUSEDwartość , ale trigger_pause_status ustawienie wstępne jest ustawione na PAUSED, harmonogram będzie niewpłacony.