Dataflow-Vorlagen

Mit Dataflow-Vorlagen können Sie eine Dataflow-Pipeline für die Bereitstellung verpacken. Jeder Nutzer mit den entsprechenden Berechtigungen kann dann die Vorlage zum Bereitstellen der Paket-Pipeline verwenden. Sie können eigene benutzerdefinierte Dataflow-Vorlagen erstellen. Google bietet vordefinierte Vorlagen für gängige Szenarien.

Vorteile

Vorlagen bieten mehrere Vorteile gegenüber der direkten Bereitstellung einer Pipeline in Dataflow:

  • Vorlagen trennen das Pipelinedesign von der Bereitstellung. Beispielsweise kann ein Entwickler eine Vorlage erstellen und ein Data Scientist kann diese zu einem späteren Zeitpunkt bereitstellen.
  • Vorlagen können Parameter enthalten, mit denen Sie die Pipeline bei der Bereitstellung der Vorlage anpassen können.
  • Sie können eine Vorlage mithilfe der Google Cloud Console, der Google Cloud CLI oder der REST API-Aufrufe bereitstellen. Sie benötigen keine Entwicklungsumgebung oder Pipeline-Abhängigkeiten, die auf Ihrem lokalen Computer installiert sind.
  • Eine Vorlage ist ein Codeartefakt, das in einem Versionsverwaltungs-Repository gespeichert und in Continuous Integration-Pipelines (CI/CD) verwendet werden kann.

Von Google bereitgestellte Vorlagen

Google bietet eine Vielzahl vordefinierter Open-Source-Dataflow-Vorlagen, die Sie für gängige Szenarien verwenden können. Weitere Informationen zu den verfügbaren Vorlagen finden Sie unter Von Google bereitgestellte Vorlagen.

Flexible Vorlagen mit klassischen Vorlagen vergleichen

Dataflow unterstützt zwei Arten von Vorlagen: flexible Vorlagen, die neuer sind, und klassische Vorlagen. Wenn Sie eine neue Dataflow-Vorlage erstellen, empfehlen wir, sie als flexible Vorlage zu erstellen.

Mit einer Flexible Vorlage wird die Pipeline zusammen mit einer Vorlagenspezifikationsdatei in Cloud Storage als Docker-Image in Artifact Registry gepackt. Die Vorlagenspezifikation enthält einen Verweis auf das Docker-Image. Wenn Sie die Vorlage ausführen, startet der Dataflow-Dienst eine Launcher-VM, ruft das Docker-Image ab und führt die Pipeline aus. Die Ausführungsgrafik wird auf Basis der vom Nutzer bereitgestellten Laufzeitparameter dynamisch erstellt. Verwenden Sie die projects.locations.flexTemplates.launch-Methode, um mit der API einen Job zu starten, der eine flexible Vorlage nutzt.

Eine klassische Vorlage enthält die JSON-Serialisierung einer Dataflow-Jobgrafik. Der Code für die Pipeline muss alle Laufzeitparameter in die Schnittstelle ValueProvider einschließen. Über diese Schnittstelle können Nutzer beim Bereitstellen der Vorlage Parameterwerte angeben. Informationen zur Verwendung der API für klassische Vorlagen finden Sie in der API-Referenzdokumentation zu projects.locations.templates.

Flexible Vorlagen haben die folgenden Vorteile gegenüber klassischen Vorlagen:

  • Im Gegensatz zu klassischen Vorlagen benötigen flexible Vorlagen die Schnittstelle ValueProvider für Eingabeparameter nicht. Nicht alle Dataflow-Quellen und -Senken unterstützen ValueProvider.
  • Während klassische Vorlagen eine statische Jobgrafik haben, können flexible Vorlagen die Jobgrafik dynamisch erstellen. Die Vorlage kann beispielsweise einen anderen E/A-Connector anhand der Eingabeparameter auswählen.
  • Eine flexible Vorlage kann die Vorverarbeitung auf einer virtuellen Maschine (VM) während der Pipelineerstellung durchführen. So können zum Beispiel Eingabeparameterwerte validiert werden.

Vorlagen-Workflow

Die Verwendung von Dataflow-Vorlagen umfasst die folgenden allgemeinen Schritte:

  1. Entwickler richten eine Entwicklungsumgebung ein und entwickeln ihre Pipeline. Die Umgebung enthält das Apache Beam-SDK und andere Abhängigkeiten.
  2. Je nach Vorlagentyp (Flex oder Classic):
    • Bei flexiblen Vorlagen packen die Entwickler die Pipeline in ein Docker-Image, übertragen das Image in die Artifact Registry und laden eine Vorlagenspezifikationsdatei in Cloud Storage hoch.
    • Bei klassischen Vorlagen führen Entwickler die Pipeline aus, erstellen eine Vorlagendatei und stellen die Vorlage in Cloud Storage bereit.
  3. Andere Nutzer senden eine Anfrage an den Dataflow-Dienst, um die Vorlage auszuführen.
  4. Dataflow erstellt eine Pipeline aus der Vorlage. Es kann fünf bis sieben Minuten dauern, bis die Pipeline ausgeführt wird.

Vorlagenjobs prüfen und auditieren

Wenn Sie laufende oder historische Dataflow-Vorlagenjobs programmatisch mit der REST API oder der Google Cloud CLI prüfen, ist die Standardansicht eine Zusammenfassungsansicht (JOB_VIEW_SUMMARY). In der Zusammenfassungsansicht werden Details zur Pipelineausführung, Vorlagenmetadaten und SDK-Pipelineoptionen weggelassen. Wenn Sie Vorlagendetails und Umgebungsoptionen abrufen möchten, müssen Sie die vollständige Jobansicht explizit anfordern.

Verwenden Sie eine der folgenden Methoden, um die Vorlagendetails für einen Job zu prüfen:

gcloud-CLI

Führen Sie den Befehl gcloud dataflow jobs describe mit dem Flag --full aus, um die vollständige Jobbeschreibung einschließlich Vorlagendetails abzurufen:

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

  • REGION: die Dataflow-Region, in der der Job ausgeführt wird.
  • JOB_ID: die ID des Dataflow-Jobs.

Führen Sie folgenden Befehl aus:

Linux, macOS oder Cloud Shell

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (PowerShell)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (cmd.exe)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Sie sollten eine Antwort ähnlich der folgenden erhalten:

environment:
  sdkPipelineOptions:
    options:
      templateLocation: gs://BUCKET_NAME/templates/TEMPLATE_NAME
id: JOB_ID
name: JOB_NAME
type: JOB_TYPE_BATCH

REST

Wenn Sie die vollständige Jobressource einschließlich Vorlagendetails abrufen möchten, senden Sie eine HTTP-GET-Anfrage an die Methode projects.locations.jobs.get mit dem Suchparameter view=JOB_VIEW_ALL:

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PROJECT_ID: Projekt-ID in Google Cloud .
  • REGION: die Dataflow-Region, in der der Job ausgeführt wird.
  • JOB_ID: die ID des Dataflow-Jobs.

HTTP-Methode und URL: 

GET https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Führen Sie folgenden Befehl aus: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL"

PowerShell

Führen Sie folgenden Befehl aus: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL" | Select-Object -Expand Content

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "id": "JOB_ID",
  "name": "JOB_NAME",
  "type": "JOB_TYPE_BATCH",
  "environment": {
    "sdkPipelineOptions": {
      "options": {
        "templateLocation": "gs://BUCKET_NAME/templates/TEMPLATE_NAME"
      }
    }
  }
}

Vorlagentypen identifizieren

Die Antwortnutzlast unterscheidet sich je nachdem, ob der Job aus einer von Google bereitgestellten Vorlage oder einer benutzerdefinierten Vorlage erstellt wurde:

  • Von Google bereitgestellte Vorlagen: Dataflow hängt automatisch vordefinierte Labels an die Jobressource an:
    • goog-dataflow-provided-template-name: der Name der Vorlage.
    • goog-dataflow-provided-template-type: der Vorlagentyp, entweder flex oder legacy (klassisch).
    • goog-dataflow-provided-template-version: die Release-Version der Vorlage.
  • Benutzerdefinierte Vorlagen: Jobs mit benutzerdefinierten Vorlagen haben keine goog-dataflow-provided-*-Labels. Sowohl Flex- als auch klassische Vorlagenjobs füllen die Option templateLocation in environment.sdkPipelineOptions aus. Wenn keine Labels vorhanden sind, können Sie den Vorlagentyp für benutzerdefinierte Jobs anhand der folgenden Felder in der vollständigen Jobantwort (JOB_VIEW_ALL) ermitteln:
    • Klassische Vorlagen: Das Feld templateLocation verweist direkt auf die bereitgestellte JSON-Vorlagendatei in Cloud Storage. Der Pfad sieht beispielsweise so aus: gs://BUCKET_NAME/templates/TEMPLATE_NAME. Jobs mit klassischen Vorlagen haben keine Container-Launcher-Image-Konfigurationen.
    • Flexible Vorlagen: Jobs mit Flexible Vorlage werden über ein Launcher-Container-Image ausgeführt. Unter dem Objekt environment enthalten Jobs mit Flexible Vorlage Spezifikationen und Parameter für den Launcher-Container (z. B. flexResourceLimits). Außerdem enthält der beim Start generierte bereitgestellte Cloud Storage-Pfad templateLocation die Job-ID.

Best Practice: Nutzerlabels beim Start anhängen

Da für die programmatische Unterscheidung von benutzerdefinierten Vorlagentypen das Abrufen und Parsen der vollständigen JOB_VIEW_ALL-Umgebungsoptionen erforderlich ist, empfehlen wir, beim Starten Ihrer Vorlagenjobs beschreibende Nutzerlabels anzuhängen. Hängen Sie beispielsweise Labels wie template-type: flex oder template-type: classic an.

Nutzerlabels werden in der Standardzusammenfassungsansicht (JOB_VIEW_SUMMARY) und in Joblistenvorgängen zurückgegeben. Mit Nutzerlabels können Sie Vorlagenjobs in Ihrem Projekt effizient filtern, suchen und prüfen, ohne die vollständige Ausführungsnutzlast für jeden Job abrufen zu müssen.

Verwenden Sie die folgenden Methoden, um beim Starten einer Vorlage Labels anzuhängen:

  • Verwenden Sie für flexible Vorlagen in der gcloud CLI das Flag --additional-user-labels im Befehl gcloud dataflow flex-template run.
  • Verwenden Sie für klassische Vorlagen in der gcloud CLI das Flag --labels im Befehl gcloud dataflow jobs run.
  • Wenn Sie die REST API verwenden, fügen Sie die Schlüssel/Wert-Zuordnung labels in den Anfragetext der Startanfrage ein.

IAM-Berechtigungen festlegen

Dataflow-Jobs, einschließlich Jobs, die über Vorlagen ausgeführt werden, verwenden zwei IAM-Dienstkonten:

  • Der Dataflow-Dienst verwendet ein Dataflow-Dienstkonto, um Google Cloud -Ressourcen zu bearbeiten, z. B. VMs zu erstellen.
  • Die Dataflow-Worker-VMs verwenden ein Worker-Dienstkonto, um auf die Dateien und andere Ressourcen Ihrer Pipeline zuzugreifen. Dieses Dienstkonto benötigt Zugriff auf alle Ressourcen, auf die der Pipelinejob verweist, einschließlich der von der Vorlage verwendeten Quellen und Senken. Weitere Informationen finden Sie unter Auf Google Cloud -Ressourcen zugreifen.

Sorgen Sie dafür, dass diese beiden Dienstkonten die entsprechenden Rollen haben. Weitere Informationen finden Sie unter Sicherheit und Berechtigungen in Dataflow.

Wenn Ihre Organisation PAB-Richtlinien (Principal Access Boundary) verwendet, können Hauptkonten (z. B. Nutzer oder Dienstkonten) möglicherweise keine von Google bereitgestellten Vorlagen aufrufen und ausführen. Weitere Informationen und Lösungen finden Sie unter Mit Principal Access Boundary-Richtlinien auf von Google bereitgestellte Vorlagen zugreifen.

Anforderungen an die Apache Beam SDK-Version

Überprüfen Sie, ob Ihre Apache Beam-SDK-Version die Vorlagenerstellung für eigene Vorlagen unterstützt.

Java

Zum Erstellen von Vorlagen mit dem Apache Beam SDK 2.x für Java benötigen Sie die Version 2.0.0-beta3 oder höher.

Python

Zum Erstellen von Vorlagen mit dem Apache Beam SDK 2.x für Python benötigen Sie die Version 2.0.0 oder höher.

Zum Ausführen von Vorlagen mit der Google Cloud-Befehlszeile benötigen Sie Google Cloud CLI Version 138.0.0 oder höher.

Vorlagen erweitern

Sie können eigene Vorlagen erstellen, indem Sie die Open-Source-Vorlagen von Dataflow erweitern. Bei einer Vorlage, die eine feste Fensterdauer verwendet, können beispielsweise Daten, die außerhalb des Fensters eingehen, verworfen werden. Verwenden Sie den Vorlagencode als Basis und ändern Sie den Code zum Aufrufen des Vorgangs .withAllowedLateness, um dieses Verhalten zu vermeiden.

Nächste Schritte