Konfigurieren von Umgebungsversionen für Pipelines

Important

Umgebungsversionen für Lakeflow-Pipelines sind in der öffentlichen Vorschau verfügbar.

Eine Umgebungsversion legt die Python-Version und die Menge der vorinstallierten Python-Bibliotheken fest, die dem Python-Code Ihrer Pipeline zur Verfügung stehen. Alle externen Abhängigkeiten, die Sie der Pipeline hinzufügen, werden über dieser Basis überschichtet.

Umgebungsversionen entkoppeln die Python-Laufzeit Ihrer Pipeline von der Databricks-Runtime-Version, auf der Ihre Pipeline ausgeführt wird. Während eine Umgebungsversion festgelegt ist, ändern Databricks-Runtime-Upgrades ihre Python Sprachversion oder vorinstallierte Bibliotheksversionen nicht. Die Python Laufzeit ist auch mit serverlosen Aufträgen und Notizbüchern konsistent, die dieselbe Umgebungsversion verwenden. Informationen zur aktuellen Databricks-Runtime-Version für Lakeflow-Pipelines finden Sie in den Versionshinweisen zu Lakeflow-Pipelines und zum Releaseupgradeprozess.

Databricks migriert berechtigte Pipelines automatisch auf eine Umgebungsversion. Siehe Automatische Migration.

Important

Pipelines mit einer Umgebungsversion führen Python-Code über Spark Connect aus, was das Verhalten einiger Pipeline-Codes verändern kann. Für die vollständige Liste der Einschränkungen und Verhaltensänderungen siehe Versionskompatibilität der Umgebung.

Requirements

Umgebungsversionen haben die folgenden Anforderungen:

  • Die Pipeline muss Unity Catalog nutzen. Hive Metastore Pipelines werden nicht unterstützt.

Unterstützte Umgebungsversionen

Lakeflow-Pipelines unterstützen die Umgebungsversionen 3 und 4 sowohl auf serverlosen als auch auf der klassischen Berechnung. Die Python Sprachversion und die vollständige Liste der vorinstallierten Python Bibliotheken, die in jeder Version verfügbar sind, finden Sie in der environment-Versionsreferenz.

Automatische Migration

Databricks migriert berechtigte Pipelines automatisch auf eine Umgebungsversion. Die Migration erfolgt beim nächsten Update einer Pipeline, erfordert keine manuellen Schritte und beinhaltet folgende Schutzmaßnahmen:

  • Das Verhalten wird vor der Migration überprüft. Databricks scannt deine Pipeline nach Codemustern, die sich unter Spark Connect anders verhalten würden, und vergleicht den Output-Plan der Pipeline vor und nach der Migration. Siehe Umgebungsversionskompatibilität.
  • Eine fehlgeschlagene Migration wird automatisch zurückgesetzt. Wenn ein migriertes Update aus irgendeinem Grund fehlschlägt, wird es gestoppt, bevor Daten geschrieben werden, und die Pipeline kehrt beim nächsten Update automatisch zur vorherigen Laufzeit zurück. Es ist keine Aktion erforderlich.
  • Deine expliziten Einstellungen werden immer respektiert. Wenn Sie die environment_version selbst festlegen, wird sie von Databricks nie überschrieben.

Sobald eine Pipeline erfolgreich migriert, läuft sie künftig auf der Umgebungsversion. Man kann die ausgewählte Version in den Pipeline-Einstellungen, die GetPipeline API-Antwort und das runtime_details Ereignisprotokoll sehen.

Was nicht automatisch migriert wird

Eine Pipeline wird nicht automatisch migriert, wenn eines der folgenden Kriterien zutrifft:

Pipelines, die nicht automatisch migriert werden, laufen weiterhin auf ihrer vorherigen Python-Laufzeit ohne Veränderung. Du kannst eine Umgebungsversion selbst aktivieren, sobald die Pipeline dafür berechtigt ist.

Aktivieren Sie selbst eine Umgebungsversion

Automatische Migration deckt die meisten Pipelines ab. Man kann auch eine Umgebungsversion explizit konfigurieren, zum Beispiel um früher zu migrieren oder eine bestimmte Version zu pinnen, über die Pipeline-Editor-UI, die Pipelines REST API oder Declarative Automation Bundles.

Bevor Sie eine Umgebungsversion explizit aktivieren, prüfen Sie, ob Ihre Pipeline mit Spark Connect kompatibel ist. Wenn Databricks erkennt, dass das Aktivieren der Version das Verhalten deiner Pipeline verändern würde, scheitert das Update, bevor irgendwelche Daten geschrieben werden, wobei ein Fehler den zu behebenden Unterschied identifiziert.

Aktivieren über die Benutzeroberfläche

  1. Klicken Sie im Pipeline-Editor auf "Einstellungen".
  2. Wählen Sie unter Pipelineumgebungdas Bleistiftsymbol aus.Bearbeiten sie die Umgebung.
  3. Wählen Sie eine Umgebungsversion aus der Dropdownliste aus.
  4. Speichern Sie die Pipelineeinstellungen.

Externe Abhängigkeiten, die im Abschnitt Pipeline-Umgebung hinzugefügt werden, bauen auf den Bibliotheken auf, die in der ausgewählten Version der Umgebung enthalten sind. Siehe Verwalten von Abhängigkeiten für Python-Pipelines.

Aktivieren über die API

Die Pipelines-REST-API akzeptiert einen environment Block beim Erstellen und Aktualisieren der Pipeline. Die Authentifizierung des persönlichen Zugriffstokens muss für den Arbeitsbereich aktiviert sein.

So erstellen Sie eine Pipeline mit einer Umgebungsversion:

curl --request POST \
  --url 'https://<workspace-host>/api/2.0/pipelines' \
  --header 'Authorization: Bearer <personal-access-token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<pipeline-name>",
    "catalog": "<catalog>",
    "schema": "<schema>",
    "channel": "CURRENT",
    "environment": {
      "environment_version": "4",
      "dependencies": [
        "simplejson==3.19.*"
      ]
    }
  }'

Um die Umgebungsversion für eine vorhandene Pipeline festzulegen, senden Sie denselben environment Block mit PUT /api/2.0/pipelines/<pipeline-id>.

Aktivieren über deklarative Automatisierungspakete

Wenn Sie eine Pipeline mit deklarativen Automatisierungspaketen erstellen, können Sie eine Umgebungsversion in der YAML-Definition der Pipeline festlegen.

  1. Stellen Sie sicher, dass Ihre Databricks CLI version v0.294.0 oder höher ist. Wenn nicht, führen Sie ein Upgrade aus, indem Sie dem Installationshandbuch folgen.
  2. Richten Sie ein Bundle ein, indem Sie dem Tutorial zum Pipeline-Bundle folgen.
  3. Suchen Sie die YAML-Datei der Pipeline in Ihrem Bundle, in der Regel <bundle-folder>/resources/<pipeline_name>_pipeline.yml.
  4. Legen Sie die Felder environment_version und dependencies in der YAML-Datei der Pipeline fest:
resources:
  pipelines:
    my_pipeline:
      name: my_pipeline
      catalog: ${var.catalog}
      schema: ${var.schema}
      root_path: '../src/my_pipeline'
      libraries:
        - glob:
            include: ../src/my_pipeline/transformations/**
      environment:
        environment_version: 4
        dependencies:
          - --editable ${workspace.file_path}

Umgebungsversion in einer Pipeline überprüfen

Um zu überprüfen, welche Umgebungsversion eine Pipeline ausführt, ob Sie sie explizit festlegen oder Databricks sie während der automatischen Migration ausgewählt hat:

  • Benutzeroberfläche: Öffnen Sie die Pipelineeinstellungen, und überprüfen Sie den Abschnitt "Pipelineumgebung ", oder überprüfen Sie den JSON-Bereich für das environment.environment_version Feld.
  • API: Rufen Sie GET /api/2.0/pipelines/<pipeline-id> auf und suchen Sie in der Antwort nach environment.environment_version. Dies zeigt eine Version an, die du explizit festgelegt hast; Um eine Version durch automatische Migration ausgewählt zu sehen, verwenden Sie das untenstehende Ereignisprotokoll.
  • Ereignisprotokoll: Inspizieren Sie das runtime_details Ereignis, das die für das Update verwendete Umgebungsversion anzeigt. Siehe Details für das Ereignis runtime_details.

Eine Umgebungsversion deaktivieren oder zurücksetzen

Du musst eine automatische Migration nicht manuell zurücksetzen. Eine Migration, die fehlschlägt, wird beim nächsten Update automatisch rückgängig gemacht. Wenn die Umgebungsversion entfernt wird, kehrt die Pipeline zur vorherigen Python Laufzeitkonfiguration zurück. Wenn etwas Unerwartetes passiert, kontaktiere den Azure Databricks Support.

Weitere Ressourcen

  • Last updated on