Разработка конвейеров с помощью декларативных пакетов автоматизации

Декларативные пакеты автоматизации (ранее известные как пакеты ресурсов Databricks) позволяют программно проверять, развертывать и запускать ресурсы Azure Databricks, такие как Декларативные конвейеры Spark Lakeflow. См. что такое декларативные пакеты автоматизации.

На этой странице описывается создание пакета для программного управления конвейером. См. Lakeflow Spark декларативные конвейеры. Пакет создается с помощью команды CLI pipelines initDatabricks, которая определяет конвейер ETL и задание для его запуска. Затем вы проверяете, развертываете и запускаете развернутый конвейер в рабочей области Azure Databricks на бессерверных вычислительных ресурсах.

Требования

• Databricks CLI версии 0.283.0 или более поздней. Чтобы проверить установленную версию интерфейса командной строки Databricks, выполните команду databricks -v. Чтобы установить интерфейс командной строки Databricks, см. статью "Установка или обновление интерфейса командной строки Databricks".
• Uv требуется для выполнения тестов и установки зависимостей для этого проекта из интегрированной среды разработки.
• Удаленная рабочая область должна иметь включенные файлы рабочей области. См. раздел "Что такое файлы рабочей области?".
• Существующий каталог данных для таблиц в потоке обработки. См. Создание каталогов.

(Необязательно) Установка модуля Python для поддержки разработки локальных конвейеров

Databricks предоставляет модуль Python для поддержки локальной разработки кода Декларативных конвейеров Lakeflow Spark, предоставляя проверку синтаксиса, автозавершение и проверку типов данных при написании кода в интегрированной среде разработки.

Модуль Python для локальной разработки доступен в PyPi. Чтобы установить модуль, см. заглушка Python для DLT.

Шаг 1. Настройка проверки подлинности

Сначала настройте проверку подлинности между Интерфейсом командной строки Databricks на компьютере разработки и рабочей областью Azure Databricks. На этой странице предполагается, что вы хотите использовать аутентификацию OAuth пользователь-к-машине (U2M) и соответствующий профиль конфигурации Azure Databricks с именем DEFAULT для аутентификации.

1. Используйте интерфейс командной строки Databricks для локального запуска управления маркерами OAuth, выполнив следующую команду для каждой целевой рабочей области.

   В следующей команде замените <workspace-url> на ваш URL-адрес Azure Databricks для рабочей области, например https://adb-1234567890123456.7.azuredatabricks.net.

   databricks auth login --host <workspace-url>
   

2. Интерфейс командной строки Databricks предлагает сохранить сведения, введенные в качестве профиля конфигурации Azure Databricks. Нажмите, Enter чтобы принять предлагаемое имя профиля, или введите имя нового или существующего профиля. Любой существующий профиль с тем же именем перезаписывается с введенными сведениями. Профили можно использовать для быстрого переключения контекста проверки подлинности в нескольких рабочих областях.

   Чтобы получить список существующих профилей в отдельном терминале или командной строке, используйте интерфейс командной строки Databricks для выполнения команды databricks auth profiles. Чтобы просмотреть существующие параметры конкретного профиля, выполните команду databricks auth env --profile <profile-name>.

3. В веб-браузере выполните инструкции на экране, чтобы войти в рабочую область Azure Databricks.

4. Чтобы просмотреть текущее значение маркера OAuth профиля и метку времени окончания срока действия маркера, выполните одну из следующих команд:

   • databricks auth token --host <workspace-url>
   • databricks auth token -p <profile-name>
   • databricks auth token --host <workspace-url> -p <profile-name>

   Если у вас есть несколько профилей с одинаковым значением --host, может потребоваться указать параметры --host и -p вместе, чтобы помочь Databricks CLI найти правильные данные о соответствии маркера OAuth.

Шаг 2. Создание пакета

Инициализация пакета с помощью конвейера:

1. Используйте терминал или командную строку, чтобы переключиться в каталог на локальном компьютере разработки, который будет содержать созданный пакет шаблона.

2. Используйте CLI Databricks, чтобы выполнить команду pipelines init.

   databricks pipelines init
   

3. Оставьте значение по умолчанию параметра Unique name for this project, либо введите другое значение, а затем нажмите my_pipeline_project. Это определяет имя корневого каталога для этого пакета. Этот корневой каталог создается в текущем рабочем каталоге.

4. Введите Initial catalog имя существующего каталога Unity.

5. Для Use a personal schema for each user working on this project?, выберите yes.

6. Для Initial language for this project, выберите python.

Шаг 3. Изучение пакета

Чтобы просмотреть файлы, созданные шаблоном, переключитесь в корневой каталог созданного пакета. Следующая структура создается по умолчанию:

my_pipeline_project
├── databricks.yml
├── pyproject.toml
├── README.md
├── resources
│   ├── my_pipeline_project_etl.pipeline.yml
│   └── sample_job.job.yml
└── src
    └── my_pipeline_project_etl
        ├── explorations
        │   └── sample_exploration.ipynb
        ├── README.md
        └── transformations
            ├── sample_trips_my_pipeline_project.py
            └── sample_zones_my_pipeline_project.py

К файлам, интересующим особый интерес, относятся следующие:

• databricks.yml: этот файл указывает программное имя пакета, содержит ссылки на файлы пакета, определяет переменные каталога и схемы и задает параметры для целевых рабочих областей.

• resources/sample_job.job.yml и resources/<project-name>_etl_pipeline.yml: эти файлы определяют задание, содержащее задачу обновления конвейера, и параметры конвейера. Сведения о параметрах конвейера см. в разделе "Конвейер".

• src/: эта папка содержит исходные файлы примера конвейера, исследования и преобразования.

  Совет

  Если вы добавляете тесты, используйте pytest для их выполнения локально.

  uv run pytest
  

• README.md: этот файл содержит дополнительные сведения о начале работы и использовании этого шаблона пакета.

Шаг 4. Проверка конфигурации пакета

Теперь проверьте, допустима ли конфигурация пакета.

1. Из корневого каталога используйте интерфейс командной строки Databricks для выполнения команды bundle validate.

   databricks bundle validate
   

2. Если возвращается сводка конфигурации пакета, проверка выполнена успешно. Если возвращаются какие-либо ошибки, исправьте ошибки и повторите этот шаг.

Шаг 5. Развертывание конвейера в удаленной рабочей области

Затем разверните пакет в удаленной рабочей области Azure Databricks и проверьте конвейер в рабочей области.

1. В корневом каталоге пакета используйте команду Databricks CLI deploy.

   databricks bundle deploy --target dev
   

   Или:

   databricks pipelines deploy --target dev
   

   Примечание.

   Шаблон по умолчанию включает задание, которое выполняет конвейер каждый день, но приостанавливается для целевого dev режима развертывания. См. режимы развертывания декларативных пакетов автоматизации.

2. Убедитесь, что пакет был развернут:

   1. На боковой панели рабочей области Azure Databricks щелкните "Рабочая область".
   2. Щелкните папку "Пользователи" ><your-username>>.bundle и найдите проект пакета.

3. Проверьте, была ли создана ваша производственная цепочка.

   1. На боковой панели рабочей области Azure Databricks щелкните "Задания и конвейеры".
   2. При необходимости выберите фильтры "Конвейеры " и " Принадлежащие мне ".
   3. Щелкните [dev <your-username>] <project-name>_etl.

При внесении изменений в пакет после этого шага необходимо повторить шаги 4–5, чтобы проверить, действительна ли конфигурация пакета, а затем повторно разверните проект.

Шаг 6. Запуск развернутого конвейера

Теперь активируйте запуск конвейера в рабочей области из командной строки.

1. В корневом каталоге используйте команду Databricks CLI pipelines run. Если в проекте существует только один конвейер, вам не нужно указывать имя конвейера.

   databricks pipelines run my_pipeline_project_etl --target dev
   

2. Скопируйте значение, которое отображается в терминале и вставьте это значение Update URL в веб-браузер, чтобы открыть рабочую область Azure Databricks.

3. В рабочей области Azure Databricks после успешного завершения работы сборки щелкните по материализованным представлениям, чтобы просмотреть детали каждого представления.

При внесении изменений в пакет после этого шага необходимо повторить шаги 4-6, чтобы проверить, действительна ли конфигурация пакета, повторно разверните проект и запустите повторно развернутый проект.

Шаг 7. Журнал выходных данных и журналы событий

Сведения, предоставляемые командами pipelines history , pipelines logs могут помочь диагностировать сбои.

Чтобы получить прошлые запуски для конвейера, выполните следующие действия.

databricks pipelines history my_pipeline_project_etl

Updates Summary for pipeline my_pipeline_project_etl:
Update ID: a62293ec-8a63-43b7-8629-b218d56dac7c
   State: COMPLETED
   Cause: API_CALL
   Creation Time: 2026-01-29T23:16:14Z
   Full Refresh: false
   Validate Only: false

Чтобы вывести (в ФОРМАТЕ JSON) события последнего обновления конвейера:

databricks pipelines logs my_pipeline_project_etl

Используется jq для фильтрации результатов. Смотрите фильтрацию выходных данных JSON с помощью jq.

Шаг 8. Очистка

На этом шаге вы удалите развернутый пакет и конвейер из рабочей области.

1. Из корневого каталога используйте интерфейс командной строки Databricks для выполнения команды pipelines destroy.

   databricks pipelines destroy --target dev
   

2. При появлении запроса на постоянное уничтожение ресурсов, конвейера и таблиц и представлений, управляемых конвейером, введите y и нажмите клавишу Enter.

3. Если вы также хотите удалить пакет с компьютера разработки, теперь можно удалить локальный каталог проекта.