Udostępnij za pośrednictwem

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 Databricks?.

Aby utworzyć pakiety i pracować z pakietami, przejdź do Tworzenie pakietów zasobów Databricks.

databricks.yml

Pakiet musi zawierać jeden (i tylko jeden) plik konfiguracji o nazwie databricks.yml w katalogu głównym folderu projektu pakietu. databricks.yml jest głównym plikiem konfiguracji, który definiuje pakiet, ale może odwoływać się do innych plików konfiguracji, takich jak pliki konfiguracji zasobów, w mapowaniu include . Konfiguracja pakietu jest wyrażona w języku YAML. Aby uzyskać więcej informacji na temat języka YAML, zobacz oficjalną specyfikację YAML.

Najprostsza składnia databricks.yml definiuje nazwę pakietu, która znajduje się w wymaganym mapowaniu najwyższego poziomu bundle, oraz docelowe wdrożenie.

bundle:
  name: my_bundle

targets:
  dev:
    default: true

Aby uzyskać szczegółowe informacje na temat wszystkich mapowań najwyższego poziomu, zobacz Mapowania.

Napiwek

Obsługa języka Python dla pakietów zasobów usługi Databricks umożliwia definiowanie zasobów w języku Python. Zobacz Konfiguracja pakietu w języku Python.

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 Informacje o 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
  deployment: Map
  git:
    origin_url: string
    branch: string

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

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

# 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 default artifact settings if not otherwise overridden in
# the targets top-level mapping.
artifacts:
  <some-unique-artifact-identifier>:
    build: string
    dynamic_version: boolean
    executable: string
    files:
      - source: string
    path: string
    type: string

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

# These are the default workspace settings if not otherwise overridden in
# the 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. 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
  resource_path: string
  root_path: string
  state_path: string

# These are the permissions to apply to resources 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 resource settings if not otherwise overridden in
# the targets top-level mapping.
resources:
  apps:
    <unique-app-name>:
      # See the REST API create request payload reference for apps.
  clusters:
    <unique-cluster-name>:
      # See the REST API create request payload reference for clusters.
  dashboards:
    <unique-dashboard-name>:
      # See the REST API create request payload reference for dashboards.
  experiments:
    <unique-experiment-name>:
      # See the REST API create request payload reference for experiments.
  jobs:
    <unique-job-name>:
      # See REST API create request payload reference for jobs.
  model_serving_endpoint:
    <unique-model-serving-endpoint-name>:
    # See the model serving endpoint request payload reference.
  models:
    <unique-model-name>:
      # See the REST API create request payload reference for models (legacy).
  pipelines:
    <unique-pipeline-name>:
      # See the REST API create request payload reference for :re[LDP] (pipelines).
  quality_monitors:
    <unique-quality-monitor-name>:
    # See the quality monitor request payload reference.
  registered_models:
    <unique-registered-model-name>:
    # See the registered model request payload reference.
  schemas:
    <unique-schema-name>:
      # See the Unity Catalog schema request payload reference.
  secret_scopes:
    <unique-secret-scope-name>:
      # See the secret scope request payload reference.
  volumes:
    <unique-volume-name>:
    # See the Unity Catalog volume request payload reference.

# 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.
    default: boolean
    git: Map
    mode: string
    permissions:
      # See the preceding "permissions" syntax.
    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

Ta sekcja zawiera kilka podstawowych przykładów, które ułatwiają zrozumienie sposobu działania pakietów i sposobu tworzenia struktury konfiguracji.

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 plik databricks.ymlkonfiguracji pakietu . Ten notatnik jest uruchamiany jako zadanie przez zdalny klaster z określonym identyfikatorem klastra. Zdalny adres URL obszaru roboczego oraz poświadczenia uwierzytelniania obszaru roboczego są odczytywane z lokalnego profilu konfiguracji obiektu wywołującego o nazwie DEFAULT.

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

Poniższy przykład dodaje element docelowy o nazwie prod, który używa innego adresu URL zdalnego obszaru roboczego oraz poświadczeń uwierzytelniania obszaru roboczego, które są odczytywane z pasującego wpisu .databrickscfg w pliku host obiektu wywołującego, z określonym adresem URL obszaru roboczego. To zadanie uruchamia ten sam notebook, ale używa innego zdalnego klastra o określonym identyfikatorze klastra.

Uwaga

Databricks zaleca używanie mapowania host zamiast mapowania default wszędzie tam, gdzie jest to możliwe, dzięki czemu pliki konfiguracji pakietu są bardziej przenośne. Ustawienie mapowania powoduje, że Interfejs wiersza polecenia (CLI) usługi Databricks znajduje pasujący profil w pliku host, a następnie używa pól tego profilu do określenia, który typ uwierzytelniania usługi Databricks użyć. Jeśli istnieje wiele profilów z pasującym host polem, należy użyć opcji --profile w poleceniach pakietowych, aby określić profil do wykorzystania.

Zwróć uwagę, że nie trzeba deklarować mapowania notebook_task w ramach mapowania prod, ponieważ przechodzi na użycie mapowania notebook_task w ramach głównego poziomu mapowania resources, jeśli mapowanie notebook_task nie jest jawnie zastępowane w ramach mapowania prod.

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

Użyj następujących poleceń bundle, aby zweryfikować, wdrożyć i uruchomić to zadanie w dev obiekcie docelowym. Aby uzyskać szczegółowe informacje na temat cyklu życia pakietu, zobacz Tworzenie pakietów zasobów usługi Databricks.

# 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 docelowego środowiska prod:

# 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

Aby uzyskać więcej modułyzacji i lepszego ponownego użycia definicji i ustawień w pakietach, podziel konfigurację pakietu na oddzielne pliki:

# databricks.yml

bundle:
  name: hello-bundle

include:
  - '*.yml'

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

# 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 następnych sekcjach opisano mapowania konfiguracji pakietu dla kluczowych poziomów. Aby uzyskać informacje o konfiguracji, zobacz Informacje o konfiguracji.

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ęcej obiektów docelowych w mapowaniu najwyższego poziomu obiektów docelowych. 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 wyłącznie do scenariuszy deweloperskich 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 Git skojarzone z pakietem, co jest przydatne do rozpowszechniania metadanych wdrożenia, które można użyć później do identyfikowania zasobów. Możesz na przykład śledzić pochodzenie repozytorium zadania wdrożonego przez CI/CD.

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. Można użyć podstawiania do odwoływania się do tej wartości w plikach konfiguracyjnych pakietu, takich jak ${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. Można użyć podstawiania do odwoływania się do tej wartości w plikach konfiguracyjnych pakietu, takich jak ${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ć ustawienia origin_url i branch wewnątrz mapowania git 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 określa wersję interfejsu CLI 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 wersjonowaniem semantycznym, a databricks_cli_version mapowanie obsługuje określanie ograniczeń wersji. Jeśli bieżąca databricks --version wartość nie znajduje się w zakresie określonym w mapowaniu pakietu databricks_cli_version, wystąpi błąd, gdy databricks bundle validate jest wykonywane na 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

uruchom_jako

Ustawienie run_as określa user_name parametr lub service_principal_name do uruchomienia pakietu. Zapewnia możliwość oddzielenia tożsamości używanej do wdrożenia zadań pakietowych lub potoków od tożsamości używanej do ich uruchamiania.

Zobacz Określ tożsamość przebiegu dla przepływu pracy pakietów zasobów usługi Databricks.

zawiera

Tablica include określa listę wzorców ścieżek zawierających pliki konfiguracyjne do włączenia do pakietu. Te wzorce ścieżek są względne względem położenia pliku konfiguracyjnego, w którym określono wzorce ścieżek.

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ć wszystkie pliki konfiguracji do uwzględnienia w pakiecie, z wyjątkiem samego pliku databricks.yml.

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, których nazwy plików rozpoczynają się od bundle i kończą na .yml. Te pliki znajdują się w tym samym folderze co plik konfiguracji pakietu:

include:
  - 'bundle*.yml'

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 podstawie dowolnej listy globów plików i ścieżek w pliku .gitignore w katalogu głównym pakietu, mapowanie include może zawierać listę globów plików, globów ścieżek lub obu, względem katalogu głównego pakietu, aby jawnie dołączyć.
  • Na podstawie dowolnej listy wzorców plików i ścieżek w pliku .gitignore znajdującym się w katalogu głównym pakietu oraz listy wzorców plików i ścieżek w mapowaniu include, mapowanie exclude może zawierać listę wzorców plików, wzorców ścieżek lub obu elementów, odnoszących się do katalogu głównego pakietu, które mają być jawnie wykluczone.

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 wzorców ścieżek exclude jest zgodna ze standardową składnią .gitignore 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 folderze my_package/dist z rozszerzeniem pliku *.whl. Ż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 dla określonego celu. Każde sync mapowanie zadeklarowane w miejscu docelowym jest scalane z wszelkimi deklaracjami mapowania najwyższego poziomu sync. Na przykład, kontynuując nawiązanie do wcześniejszego przykładu, następujące mapowanie na poziomie include łączy się z mapowaniem targets w nadrzędnym mapowaniu include:

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

Ścieżki

Mapowanie sync może zawierać mapowanie paths, które określa lokalne ścieżki 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 w databricks.yml synchronizuje folder common znajdujący się na jednym poziomie powyżej katalogu głównego pakietu oraz sam katalog główny 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/
    ...

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 utworzyć plik wheel dla języka Python przed wdrożeniem, ustaw to 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 kompilacji wheel w języku Python jest to ścieżka do pliku setup.py powiązanego z plikiem wheel w Pythonie. Jeśli path jest pominięty, CLI dla Databricks próbuje znaleźć plik wheel setup.py języka 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ą zależne od 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 tworzenia pakietów wheel w języku Python, CLI usługi Databricks zakłada, że może znaleźć lokalnie zainstalowany pakiet Python wheel do uruchamiania kompilacji i domyślnie uruchamia polecenie python setup.py bdist_wheel podczas każdego wdrażania pakietu. Aby określić wiele poleceń kompilacji, należy oddzielić każde polecenie znakiem podwójnego i (&&).
  • dynamic_version umożliwia aktualizację wersji wheel na podstawie znacznika czasu pliku wheel. Następnie można wdrożyć nowy kod bez konieczności aktualizowania wersji w setup.py lub pyproject.toml. To ustawienie jest prawidłowe tylko wtedy, gdy type jest ustawione na whl.

Poniższa przykładowa konfiguracja kompiluje koło przy użyciu poezji. Aby uzyskać pełny przykładowy pakiet, który wykorzystuje artifacts do zbudowania koła, zobacz w temacie Build a Python wheel file using Databricks Asset Bundles (Tworzenie pliku wheel języka Python przy użyciu pakietów zasobów usługi Databricks).

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

Dla przykładowej konfiguracji, która buduje plik JAR i wgrywa go do Unity Catalog, zobacz Pakiet, który wgrywa plik JAR do Unity Catalog.

Napiwek

Ustawienia artefaktów w pakietach można definiować, łączyć i zastępować, zgodnie z opisem w temacie Definiowanie ustawień artefaktów w pakietach zasobów usługi Databricks.

Zmienne

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 odnieść się do zmiennej niestandardowej w ramach konfiguracji pakietu, użyj zamiennika ${var.<variable_name>}.

Aby uzyskać więcej informacji na temat niestandardowych zmiennych i podstawień, zapoznaj się z Podstawianiem i zmiennymi w pakietach zasobów Databricks.

obszar roboczy

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

Ważne

Prawidłowe ścieżki obszaru roboczego usługi Databricks rozpoczynają się od /Workspace, a dla artefaktów również obsługiwane jest /Volumes. Niestandardowe ścieżki obszaru roboczego są automatycznie poprzedzone prefiksem /Workspace, więc jeśli używasz podstawiania ścieżki obszaru roboczego w swojej niestandardowej ścieżce, takiej jak ${workspace.file_path}, nie musisz dodawać /Workspace na początku ścieżki.

ścieżka główna

To mapowanie workspace może zawierać dodatkowe mapowanie root_path, aby określić nie-domyślną ścieżkę główną do zastosowania w obszarze roboczym zarówno dla wdrożeń, jak i przebiegów pracy, na przykład:

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

Domyślnie interfejs wiersza polecenia Databricks używa domyślnej ścieżki root_path, która wykorzystuje /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}.

ścieżka_artefaktu

To mapowanie workspace może również zawierać mapowanie artifact_path określające niestandardową ścieżkę artefaktu do użycia w obszarze roboczym zarówno dla wdrożeń, jak i procesó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 interfejs wiersza polecenia Databricks używa domyślnej ścieżki artifact_path, która wykorzystuje ${workspace.root}/artifacts.

Uwaga

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

ścieżka pliku

To mapowanie workspace może również zawierać mapowanie file_path w celu określenia nie-domyślnej ścieżki 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 interfejs wiersza polecenia Databricks używa domyślnej ścieżki file_path, która wykorzystuje ${workspace.root}/files.

ścieżka_stanu

Mapowanie state_path domyślnie jest ustawione na tę domyślną ścieżkę ${workspace.root}/state i reprezentuje ścieżkę w obszarze roboczym w celu przechowywania informacji o stanie wdrożeń programu Terraform.

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ń przy użyciu ${var.*} składni.

  • Mapowanie profile (lub --profile lub -p podczas uruchamiania poleceń walidacji, wdrożenia, uruchomienia i usunięcia 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 mapowania host (lub opcji --profile i -p podczas uruchamiania poleceń walidowania, wdrażania, uruchamiania i niszczenia pakietu za pomocą interfejsu wiersza polecenia Databricks) zamiast mapowania profile, ponieważ sprawia to, że pliki konfiguracji pakietu są bardziej przenośne. Ustawienie mapowania powoduje, że Interfejs wiersza polecenia (CLI) usługi Databricks znajduje pasujący profil w pliku host, a następnie używa pól tego profilu do określenia, który typ uwierzytelniania usługi Databricks użyć. Jeśli w pliku istnieje wiele profilów z pasującym polem host, musisz użyć mapowania .databrickscfg (lub opcji wiersza polecenia profile albo --profile), aby poinstruować interfejs wiersza polecenia usługi Databricks, którego profilu użyć. Aby zobaczyć przykład, odnieś się do 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 wartością client_id, a następnie określić nazwę profilu z mapowaniem profile (lub za pomocą opcji --profile lub -p podczas uruchamiania poleceń bundle validate, deploy, run i destroy za pomocą interfejsu wiersza polecenia 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ć tajnej wartości OAuth usługi Azure Databricks w pliku konfiguracji pakietu. Zamiast tego ustaw lokalną zmienną środowiskową DATABRICKS_CLIENT_SECRET. Możesz też dodać wartość client_secret do profilu konfiguracji, a następnie określić nazwę profilu przy użyciu mapowania profile (lub używając opcji --profile lub -p podczas uruchamiania poleceń validate, deploy, run i destroy w interfejsie wiersza polecenia Databricks CLI).

  • W przypadku uwierzytelniania za pomocą Azure CLI używa się mapowania 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 wartością azure_workspace_resource_id, a następnie określić nazwę profilu z mapowaniem profile (lub za pomocą opcji --profile lub -p podczas uruchamiania poleceń bundle validate, deploy, run i destroy za pomocą interfejsu wiersza polecenia Databricks). Zobacz Uwierzytelnianie Azure CLI.

  • W przypadku uwierzytelniania sekretów klienta Azure za pomocą zasad usługi używane są mapowania azure_workspace_resource_id, azure_tenant_id, i 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_id i azure_client_id, a następnie określić nazwę profilu za pomocą mapowania profile (lub przy użyciu opcji --profile lub -p podczas uruchamiania pakietu przy użyciu poleceń validate, deploy, run i destroy za pomocą Databricks CLI). Zobacz Uwierzytelnianie usługi głównej MS Entra.

    Uwaga

    Nie można określić wartości tajnego klienta Azure w pliku konfiguracji pakietu. Zamiast tego ustaw lokalną zmienną środowiskową ARM_CLIENT_SECRET. Możesz też dodać wartość azure_client_secret do profilu konfiguracji, a następnie określić nazwę profilu przy użyciu mapowania profile (lub używając opcji --profile lub -p podczas uruchamiania poleceń validate, deploy, run i destroy w interfejsie wiersza polecenia Databricks CLI).

  • W przypadku uwierzytelniania tożsamości zarządzanych platformy Azure używane są mapowania azure_use_msi, azure_client_id, i 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_id i 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 pakietu przy użyciu poleceń validate, deploy, run i destroy za pomocą 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ć wartość azure_environment do profilu konfiguracji, a następnie określić nazwę profilu przy użyciu mapowania profile (lub używając opcji --profile lub -p podczas uruchamiania poleceń validate, deploy, run i destroy w interfejsie wiersza polecenia Databricks CLI).

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

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 głównego użytkownika usługi, które są stosowane do wszystkich zadań, potoków, eksperymentów i modeli zdefiniowanych w pakiecie resources.

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

zasoby

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

To resources mapowanie może pojawić się jako mapowanie najwyższego poziomu lub może być elementem podrzędnym jednego lub więcej obiektów docelowych w mapowaniu najwyższego poziomu i może 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 deklaracje zasobów indywidualnych wykorzystują ładunek żądania operacji tworzenia odpowiedniego obiektu, wyrażony w YAML, do określenia zasobu. 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 polecenie databricks bundle schema wyświetla wszystkie obsługiwane schematy obiektów. Ponadto polecenie databricks bundle validate zwraca ostrzeżenia, 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 pakietu zasobów usługi Databricks i przykłady konfiguracji pakietu.

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 zdefiniowany, może występować tylko jako mapowanie najwyższego poziomu.

Ustawienia w przestrzeni roboczej najwyższego poziomu, artefaktach i zasobach są używane, jeśli nie zostały określone w mapowaniu, ale wszelkie niezgodne ustawienia są zastępowane przez ustawienia wewnątrz celu.

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 cel nie jest skonfigurowany lub chcesz zweryfikować, wdrożyć i uruchomić zadania lub potoki w określonym celu, użyj -t opcji poleceń pakietu.

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

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ć identyfikatory uruchomienia dla pakietów, można określić run_as dla każdego celu, zgodnie z opisem w temacie Określanie identyfikatora uruchomienia dla przepływu pracy pakietów zasobów 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 cel produkcyjny.

targets:
  prod:
    mode: production

Można dostosować niektóre zachowania, używając mapowania presets. Aby uzyskać listę dostępnych ustawień wstępnych, zobacz Niestandardowe ustawienia wstępne. W poniższym przykładzie przedstawiono dostosowany cel produkcji, dodający prefiksy i tagujący wszystkie zasoby produkcyjne:

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.