Konwertować potok danych na projekt pakietu

Istniejący potok można przekształcić w projekt Declarative Automation Bundles. Pakiety umożliwiają definiowanie konfiguracji przetwarzania danych usługi Azure Databricks i zarządzanie nią w jednym, kontrolowanym źródle pliku YAML, który zapewnia łatwiejszą konserwację i umożliwia automatyczne wdrażanie w środowiskach docelowych.

Aby zapoznać się z samouczkiem, który używa databricks pipelines poleceń do tworzenia projektu potoków, a następnie wdraża i uruchamia potok, zobacz Tworzenie potoków przy użyciu pakietów deklaratywnej automatyzacji.

Omówienie procesu konwersji

Diagram przedstawiający konkretne kroki konwertowania istniejącego potoku na pakiet

Kroki, które należy wykonać w celu przekonwertowania istniejącego potoku na pakiet, są następujące:

Sprawdź, czy masz dostęp do wcześniej skonfigurowanego potoku, który chcesz przekonwertować na pakiet.
Utwórz lub przygotuj folder (najlepiej w hierarchii kontrolowanej przez źródło) do przechowywania pakietu.
Wygeneruj konfigurację pakietu z istniejącego potoku, korzystając z Databricks CLI.
Przejrzyj wygenerowaną konfigurację pakietu, aby upewnić się, że została ukończona.
Połącz pakiet z oryginalnym potokiem.
Wdróż pipeline w docelowym obszarze roboczym przy użyciu konfiguracji bundla.

Requirements

Przed rozpoczęciem musisz mieć następujące elementy:

Interfejs wiersza polecenia (CLI) Databricks zainstalowany na lokalnej maszynie deweloperskiej. Do korzystania z pakietów deklaratywnej automatyzacji wymagany jest interfejs wiersza polecenia usługi Databricks w wersji 0.218.0 lub nowszej.
Identyfikator istniejącego potoku deklaratywnego, którym będziesz zarządzać przy użyciu pakietu. Aby dowiedzieć się, jak uzyskać ten identyfikator, zobacz Uzyskiwanie istniejącej definicji ścieżki za pomocą interfejsu użytkownika.
Autoryzacja dla obszaru roboczego usługi Azure Databricks, w którym działa istniejący potok. Aby skonfigurować uwierzytelnianie i autoryzację dla wywołań interfejsu wiersza polecenia usługi Databricks, zobacz Autoryzowanie dostępu do zasobów usługi Azure Databricks.
Aby uzyskać pełny zestaw uprawnień wymaganych do tworzenia, uruchamiania, odświeżania i wyświetlania potoków oraz ich danych wyjściowych, zobacz Zarządzanie tożsamościami, uprawnieniami i uprawnieniami dla potoków.

Krok 1. Konfigurowanie folderu dla projektu pakietu

Musisz mieć dostęp do repozytorium Git skonfigurowanego w usłudze Azure Databricks jako folderu Git. Utworzysz projekt pakietu w tym repozytorium, który zastosuje kontrolę źródła i udostępni go innym współpracownikom za pośrednictwem folderu Git w odpowiednim obszarze roboczym usługi Azure Databricks. (Aby uzyskać więcej informacji na temat folderów Git, zobacz Foldery Git usługi Azure Databricks).

Przejdź do głównej lokalizacji sklonowanego repozytorium Git na swoim komputerze lokalnym.
W odpowiednim miejscu w hierarchii folderów utwórz folder przeznaczony specjalnie dla projektu pakietu. Przykład:
```
mkdir -p ~/source/my-pipelines/ingestion/events/my-bundle
```
Zmień bieżący katalog roboczy na ten nowy folder. Przykład:
```
cd ~/source/my-pipelines/ingestion/events/my-bundle
```
Zainicjuj nowy pakiet, uruchamiając polecenie:
```
databricks bundle init
```
Odpowiedz na wezwania. Po zakończeniu będziesz mieć plik konfiguracji projektu o nazwie databricks.yml w nowym folderze głównym projektu. Ten plik jest wymagany do wdrożenia "pipeline" z poziomu wiersza polecenia. Aby uzyskać więcej informacji na temat tego pliku konfiguracji, zobacz Deklaratywne konfiguracje pakietów automatyzacji.

Krok 2: Utwórz konfigurację potoku

Z tego nowego katalogu w sklonowanym drzewie folderów repozytorium Git uruchom polecenie generowania pakietu interfejsu wiersza polecenia usługi Databricks, podając identyfikator potoku jako <pipeline-id>:

databricks bundle generate pipeline --existing-pipeline-id <pipeline-id> --profile <profile-name>

Po uruchomieniu polecenia generate tworzony jest plik konfiguracji pakietu dla potoku w folderze resources pakietu i pobierane są wszystkie odwołane artefakty do folderu src. Flaga --profile (lub -p) jest opcjonalna, ale jeśli masz profil konfiguracji usługi Databricks (określony w pliku .databrickscfg utworzonym podczas instalowania interfejsu wiersza polecenia usługi Databricks), którego chcesz użyć zamiast profilu domyślnego, podaj go w tym poleceniu. Aby uzyskać informacje o profilach konfiguracji usługi Databricks, zobacz profile konfiguracji usługi Azure Databricks.

Wskazówka

Jeśli masz istniejący projekt Spark Deklaratywne Potoki (SDP) (ma plik spark-pipeline.yml), możesz skopiować ten projekt potoku do folderu src pakietu, a następnie użyć polecenia databricks pipelines generate, aby wygenerować konfigurację pakietu. Zobacz databricks pipelines generate.

Krok 3. Przeglądanie plików projektu pakietu

Po zakończeniu bundle generate polecenia zostaną utworzone dwa nowe foldery:

resources to podkatalog projektu zawierający pliki konfiguracji projektu.
src to folder projektu, w którym są przechowywane pliki źródłowe, takie jak zapytania i notesy.

Polecenie tworzy również kilka dodatkowych plików:

*.pipeline.yml w podkatalogu resources. Ten plik zawiera konkretną konfigurację i ustawienia dla twojego pipeline'u.
Pliki źródłowe, takie jak zapytania SQL w podkatalogu src, skopiowane z istniejącej ścieżki przetwarzania.

├── databricks.yml                            # Project configuration file created with the bundle init command
├── resources/
│   └── {your-pipeline-name.pipeline}.yml     # Pipeline configuration
└── src/
    └── {source folders and files...}         # Your pipeline's declarative queries

Krok 4. Powiązanie pipeline'u pakietu z istniejącym pipeline'em

Musisz połączyć lub powiązać, definicję potoku w pakiecie z istniejącym potokiem, aby zachować aktualność podczas wprowadzania zmian. W tym celu uruchom polecenie CLI Databricks bundle deployment bind:

databricks bundle deployment bind <pipeline-name> <pipeline-ID> --profile <profile-name>

<pipeline-name> jest nazwą rurociągu. Ta nazwa powinna być taka sama jak wartość ciągu z prefiksem nazwy pliku dla konfiguracji potoku w nowym katalogu resources. Jeśli na przykład masz plik konfiguracji potoku o nazwie ingestion_data_pipeline.pipeline.yml w folderze resources, musisz podać ingestion_data_pipeline jako nazwę potoku.

<pipeline-ID> jest identyfikatorem pipeline'u. Jest taki sam jak ten, który skopiowałeś jako część wymagań tych instrukcji.

Krok 5. Wdróż potok przy użyciu nowego pakietu

Teraz wdróż pakiet potokowy w docelowym obszarze roboczym przy użyciu polecenia bundle deploy usługi Databricks CLI:

databricks bundle deploy --target <target-name> --profile <profile-name>

Flaga --target jest wymagana i musi być ustawiona na ciąg zgodny ze skonfigurowaną nazwą docelowego obszaru roboczego, taką jak development lub production.

Jeśli to polecenie zakończy się pomyślnie, to masz teraz konfigurację potoku w zewnętrznym projekcie, który można załadować do innych obszarów roboczych, uruchomić oraz łatwo udostępnić innym użytkownikom usługi Azure Databricks na twoim koncie.

Promuj w różnych środowiskach z celami

Pakiet definiuje w databricks.yml nazwane środowiska wdrożeniowe zwane targetami, z których każde odwołuje się do własnej przestrzeni roboczej, katalogu i wartości zmiennych. Cele to sposób promowania tego samego pipeline'u poprzez programowanie, staging i produkcję, wdrażając identyczny kod źródłowy do każdego kolejnego środowiska bez jego edytowania:

bundle:
  name: orders_pipeline

variables:
  catalog:
    description: Unity Catalog to write to
    default: dev_catalog

targets:
  dev:
    mode: development
    default: true
    variables:
      catalog: dev_catalog

  prod:
    mode: production
    variables:
      catalog: prod_catalog
    run_as:
      service_principal_name: '12345678-90ab-cdef-1234-567890abcdef'

Wartość mode, którą ustawisz dla każdego elementu docelowego, zmienia sposób jego wdrażania:

mode: development Oznacza cel jako osobiste, podstawowe zadanie. Zasoby mają prefiks, [dev username] a harmonogramy są domyślnie wstrzymywane, więc twoja praca nie wpływa na nikogo innego.
mode: production wyłącza te domyślne ustawienia bezpieczeństwa. W połączeniu z run_as pozwala to uruchamiać potok jako jednostka usługi zamiast konta użytkownika, dzięki czemu uruchomienia nie przestają działać, gdy ktoś odchodzi z zespołu lub zmienia rolę. Azure Databricks rekomenduje użycie jednostki usługi w środowiskach przejściowych i produkcyjnych. service_principal_name przyjmuje identyfikator aplikacji jednostki usługi, a nie jej nazwę wyświetlaną. Możesz pobrać identyfikator aplikacji ze strony operatora w ustawieniach administratora przestrzeni roboczej.

Aby poznać pełny sposób działania trybów, zobacz Tryby wdrażania pakietów Declarative Automation Bundles oraz Określanie tożsamości uruchomieniowej dla przepływu pracy Declarative Automation Bundles.

Aby promować pakiet, wdrażaj ten sam pakiet kolejno do każdego środowiska docelowego, weryfikując każdy etap:

databricks bundle validate --target prod
databricks bundle deploy --target prod
databricks bundle run orders_pipeline --target prod

Zamiast twardo kodować nazwy katalogów lub ścieżki źródłowe dla każdego środowiska w kodzie transformacji, przekaż te wartości z obiektu docelowego, aby ten sam kod źródłowy działał bez zmian wszędzie. Sposób, w jaki je ustawisz, zależy od języka źródłowego. Parametry potoku dotyczą wyłącznie kodu źródłowego SQL. W przypadku kodu źródłowego w języku Python użyj pola pipeline configuration i odczytaj wartości za pomocą spark.conf.get():

resources:
  pipelines:
    orders_pipeline:
      name: orders-pipeline
      # For SQL source code. Reference as ${source_catalog}.
      parameters:
        source_catalog: ${var.catalog}
        source_schema: raw
      # For Python source code. Read with spark.conf.get("source_catalog").
      configuration:
        source_catalog: ${var.catalog}
        source_schema: raw

Więcej informacji o parametryzowaniu kodu potoku można znaleźć w artykule Używanie parametrów w potokach.

Skonfiguruj CI/CD

Ponieważ przekonwertowany potok jest zdefiniowany w całości jako pakiet (plik YAML i pliki źródłowe w repozytorium Git), skonfigurowanie dla niego ciągłej integracji i ciągłego dostarczania (CI/CD) oznacza uruchamianie poleceń pakietu w systemie CI, takim jak GitHub Actions lub Azure DevOps. Dla każdego pull requestu uruchamiany jest odpowiedni test bazowy:

pytest dla twoich funkcji transformacji nadających się do testowania jednostkowego. Zobacz Testowanie jednostkowe potoków.
databricks bundle validate --target <env> aby wyłapać błędy konfiguracyjne.
Opcjonalnie można w roboczym targetcie databricks bundle run weryfikować oczekiwania na podstawie danych przykładowych.

Poniższy przepływ pracy GitHub Actions wdraża na środowisko staging po scaleniu do main, używając federacji OpenID Connect (OIDC) zamiast zapisanego tokena:

# .github/workflows/deploy.yml
name: Deploy pipeline bundle

on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    env:
      DATABRICKS_AUTH_TYPE: github-oidc
      DATABRICKS_HOST: ${{ vars.DATABRICKS_HOST }}
      DATABRICKS_CLIENT_ID: ${{ vars.DATABRICKS_CLIENT_ID }} # Service principal application ID
    steps:
      - uses: actions/checkout@v4

      - name: Install Databricks CLI
        uses: databricks/setup-cli@main

      - name: Validate bundle
        run: databricks bundle validate --target staging

      - name: Deploy bundle
        run: databricks bundle deploy --target staging

Zabezpiecz wdrożenie produkcyjne za ręczną akceptacją (na przykład drugie zadanie wymagające zgody GitHub Environment lub osobny etap w Azure DevOps), aby osoba wyraźnie zatwierdziła każdą promocję. Zadanie produkcyjne jest wykonywane databricks bundle deploy --target prod z użyciem zasady usługowej przypisanej do przestrzeni roboczej produkcji. Więcej informacji znajdziesz w CI/CD on Azure Databricks.

Rozwiązywanie problemów

Problematyka	Rozwiązanie
Błąd "nie znaleziono`databricks.yml`" podczas uruchamiania `bundle generate`	`bundle generate` Obecnie polecenie nie tworzy automatycznie pliku konfiguracji pakietu (`databricks.yml`). Musisz utworzyć plik przy użyciu `databricks bundle init` lub ręcznie.
Istniejące ustawienia potoku nie są zgodne z wartościami w wygenerowanej konfiguracji potoku YAML	Identyfikator pipeline nie pojawia się w pliku konfiguracyjnym pakietu YML. Jeśli zauważysz inne brakujące ustawienia, możesz je ręcznie zastosować.

Porady dotyczące sukcesu

Zawsze używaj kontroli wersji. Jeśli nie używasz folderów Git w Databricks, zapisz podkatalogi i pliki projektu w repozytorium Git lub innym repozytorium kontrolowanym przez wersję.
Przetestuj potok w środowisku nieprodukcyjnym (takim jak środowisko "deweloperskie" lub "testowe") przed wdrożeniem go w środowisku produkcyjnym. Łatwo jest wprowadzić błędną konfigurację przypadkowo.

Dodatkowe zasoby

Aby uzyskać więcej informacji na temat używania pakietów do definiowania przetwarzania danych i zarządzania nimi, zobacz:

Co to są pakiety automatyzacji deklaratywnej?
Opracowywanie potoków przy użyciu pakietów automatyzacji deklaratywnej. W tym temacie opisano tworzenie pakietu dla nowego potoku, zamiast istniejącego, z plikami źródłowymi z kontrolą wersji, które dostarczasz na potrzeby przetwarzania.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-09-11