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?

Aby utworzyć pakiety i pracować z pakietami, zobacz Tworzenie pakietów zasobów usługi Databricks.

Omówienie

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ć szczegółowe informacje na temat każdego mapowania najwyższego poziomu, zobacz Mapowania.

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

Specyfikacja

Poniższa specyfikacja YAML zawiera klucze konfiguracji najwyższego poziomu dla pakietów zasobów usługi Databricks. Aby uzyskać informacje o konfiguracji, zobacz Configuration reference (Dokumentacja konfiguracji ).

# 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:
  clusters:
    <some-unique-programmatic-identifier-for-this-cluster>:
      # See the REST API create request payload reference for clusters.
  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.
  volumes:
    <some-unique-programmatic-identifier-for-this-volume>:
    # See the Unity Catalog volume 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. Adres URL zdalnego obszaru roboczego oraz poświadczenia do uwierzytelnienia obszaru roboczego są odczytywane z lokalnego profilu konfiguracji użytkownika 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 host wiele profilów z pasującym .databrickscfg 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

W poniższym przykładzie dodano element docelowy o nazwie prod, który korzysta z innego adresu URL zdalnego obszaru roboczego oraz poświadczeń uwierzytelniania, odczytywanych z odpowiedniego wpisu .databrickscfg w pliku host obiektu wywołującego 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
• synchronizacji
• 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 bundle najwyższego poziomu name 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ępowanie cluster_id jest przeznaczone tylko dla scenariuszy przeznaczonych tylko do programowania i jest obsługiwane tylko dla obiektu docelowego, który ma mapowanie mode 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}.

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 najwyższego poziomu mapowanie variables, w którym zdefiniowano zmienne niestandardowe. Dla każdej zmiennej ustaw opcjonalny opis, wartość domyślną, czy zmienna niestandardowa jest typem złożonym, lub wyszukiwanie 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 jest ustawiona na 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

Należy na stałe wprowadzić wartości dla następujących mapowań workspace w celu uwierzytelniania w usłudze Azure Databricks. Na przykład nie można określić zmiennych niestandardowych dla wartości tych mapowań, korzystając ze składni ${var.*}.

• 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 odpowiada temu, który został utworzony podczas konfigurowania Databricks CLI.

  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 host wiele profilów z pasującym .databrickscfg 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 --profile podczas uruchamiania pakietu weryfikujące, wdrażać, uruchamiać i niszczyć polecenia za pomocą -p interfejsu wiersza polecenia usługi Databricks). Zobacz Autoryzowanie nienadzorowanego dostępu do zasobów usługi Azure Databricks przy użyciu jednostki usługi przy użyciu protokołu OAuth.

  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 --profile podczas uruchamiania pakietu weryfikowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą -p 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 --profile podczas uruchamiania pakietu weryfikujące, wdrażać, uruchamiać i niszczyć polecenia za pomocą -p 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 środowiskowych DATABRICKS_AZURE_RESOURCE_ID, ARM_TENANT_IDi ARM_CLIENT_ID, odpowiednio. Możesz też utworzyć profil konfiguracji z wartościami azure_workspace_resource_id, azure_tenant_idi azure_client_id, a następnie określić nazwę profilu za pomocą mapowania profile (lub przy użyciu opcji --profile lub -p podczas uruchamiania komendy walidacji, wdrażania, uruchamiania i niszczenia, korzystając z interfejsu wiersza poleceń Databricks CLI). 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 --profile podczas uruchamiania pakietu weryfikowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą -p 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 środowiskowych ARM_USE_MSI, ARM_CLIENT_IDi DATABRICKS_AZURE_RESOURCE_ID, odpowiednio. Możesz też utworzyć profil konfiguracji z wartościami azure_use_msi, azure_client_idi azure_workspace_resource_id, a następnie określić nazwę profilu za pomocą mapowania profile (lub przy użyciu opcji --profile lub -p podczas uruchamiania komendy walidacji, wdrażania, uruchamiania i niszczenia, korzystając z interfejsu wiersza poleceń Databricks CLI). 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 --profile podczas uruchamiania pakietu weryfikowania, wdrażania, uruchamiania i niszczenia poleceń za pomocą -p 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, szczególnie w przypadkach, gdy interfejs wiersza polecenia usługi Databricks wnioskowa nieoczekiwany typ uwierzytelniania. Zobacz Autoryzacja dostępu do zasobów 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:

• type jest wymagany w przypadku kompilacji `wheel` dla Pythona. Aby skompilować plik wheel języka Python przed wdrożeniem, ustaw go na whl. Aby utworzyć inne artefakty, to ustawienie nie musi być określone.
• path jest opcjonalną ścieżką. Ścieżki są zależne od lokalizacji pliku konfiguracji pakietu. W przypadku budowy Python wheel jest to ścieżka do pliku setup.py Python wheel. Jeśli path nie jest uwzględniona, interfejs wiersza polecenia usługi Databricks próbuje znaleźć plik setup.py pliku koła Python w katalogu głównym pakietu.
• files jest opcjonalnym mapowaniem zawierającym mapowanie source podrzędne, którego można użyć do określenia utworzonych artefaktów. Ścieżki są powiązane z lokalizacją 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 (&&).

Poniższa przykładowa konfiguracja kompiluje koło przy użyciu poezji. Aby uzyskać kompletny przykładowy pakiet, który używa artifacts do tworzenia koła, zobacz Develop a Python wheel file using Databricks Asset Bundles.

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

Przykładowa konfiguracja, która kompiluje plik JAR i przekazuje go do Unity Catalog, zobacz pakiet, który przekazuje plik JAR do Unity Catalog.

Napiwek

Możesz zdefiniować, połączyć i zastąpić ustawienia artefaktów w pakietach zgodnie z opisem w Definiowanie ustawień artefaktów w pakietach zasobów usługi Databricks.

zawierać

Tablica include określa listę ścieżek globs zawierających 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 mapowanie resources może występować jako mapowanie poziomu najwyższego lub może być elementem podrzędnym jednego lub więcej celów w mapowaniu celów najwyższego poziomu , i obejmuje 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.

Poniższa przykładowa konfiguracja definiuje zasób zadania:

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

Aby uzyskać więcej informacji na temat zasobów obsługiwanych w pakietach, a także typowych konfiguracji i przykładów, zobacz zasoby pakietów zasobów Databricks i przykłady konfiguracji pakietów .

synchronizacja

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 mapowania sync określają listę plików lub folderów do uwzględnienia w ramach wdrożeń pakietów lub ich wykluczania w zależności od następujących reguł:

• Na bazie jakiejkolwiek listy wzorców plików i ścieżek znajdującej się w pliku .gitignore w katalogu głównym pakietu, mapowanie include może zawierać listę wzorców plików, wzorców ścieżek lub obu, względem katalogu głównego pakietu, aby jednoznacznie dołączyć.
• Na podstawie dowolnej listy globów plików i ścieżek w pliku .gitignore w katalogu głównym pakietu oraz listy globów plików i ścieżek w mapowaniu include, mapowanie exclude może zawierać listę globów plików, globów ścieżek lub obu elementów względem katalogu głównego pakietu, aby jawnie określić elementy do wykluczenia.

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ędne w odniesieniu do plików i katalogów zakotwiczonych w folderze, w którym ustawiono mapowanie paths. Jeśli jedna lub więcej wartości ścieżki przechodzi w górę katalogu do przodka katalogu głównego pakietu, ścieżka główna jest dynamicznie ustalana, aby zapewnić, że struktura folderów pozostaje nienaruszona. Jeśli na przykład folder główny pakietu ma nazwę my_bundle , ta konfiguracja jest synchronizowana databricks.yml z common 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

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 mapowanie default na wartość 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ć rozwój i stosowanie najlepszych praktyk CI/CD, pakiety zasobów Databricks oferują tryby wdrażania dla celów, które określają 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 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 cel rozwoju, dodaj mapowanie mode ustawione na development. Aby określić, że element docelowy jest traktowany jako cel produkcyjny, dodaj mapowanie mode 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

Jeśli ustawiono zarówno mode, jak i presets, 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 UNPAUSED, ale ustawienie wstępne trigger_pause_status jest ustawione na PAUSED, harmonogram zostanie wznowiony.