Flexible Vorlagen konfigurieren

Auf dieser Seite werden verschiedene Konfigurationsoptionen für flexible Dataflow-Vorlagen dokumentiert, einschließlich:

Berechtigungen
Dockerfile-Umgebungsvariablen
Paketabhängigkeiten
Docker-Images
Pipelineoptionen
Staging- und temporäre Speicherorte

In der Anleitung zur Flex-Vorlage finden Sie ein Beispiel für eine Flex-Vorlage.

Informationen zu Flex-Vorlagenberechtigungen

Wenn Sie mit Flex-Vorlagen arbeiten, benötigen Sie drei Gruppen von Berechtigungen:

Berechtigungen zum Erstellen von Ressourcen
Berechtigungen zum Erstellen einer Flex-Vorlage
Berechtigungen zum Ausführen einer Flex-Vorlage

Berechtigungen zum Erstellen von Ressourcen

Wenn Sie eine Flex-Vorlagenpipeline entwickeln und ausführen möchten, müssen Sie verschiedene Ressourcen erstellen (z. B. einen Staging-Bucket). Für einmalige Aufgaben können Sie die einfache Rolle Inhaber verwenden.

Berechtigungen zum Erstellen einer Flex-Vorlage

Als Entwickler einer Flex-Vorlage müssen Sie die Vorlage erstellen und Nutzern zur Verfügung zu stellen. Beim Erstellen wird eine Vorlagenspezifikation in einen Cloud Storage-Bucket hochgeladen. Außerdem wird ein Docker-Image mit dem Code und mit den Abhängigkeiten bereitgestellt, die zum Ausführen der Pipeline erforderlich sind. Zum Erstellen einer Flex-Vorlage benötigen Sie Lese- und Schreibzugriff auf Cloud Storage sowie Artifact Registry-Writer-Zugriff auf Ihr Artifact Registry-Repository. Sie können diese Berechtigungen durch Zuweisung folgender Rollen erteilen:

Storage-Administrator (roles/storage.admin)
Cloud-Build-Bearbeiter (roles/cloudbuild.builds.editor)
Artifact Registry-Writer (roles/artifactregistry.writer)

Berechtigungen zum Ausführen einer Flex-Vorlage

Wenn Sie eine Flex-Vorlage ausführen, erstellt Dataflow einen Job für Sie. Zum Erstellen des Jobs benötigt das Dataflow-Dienstkonto die folgende Berechtigung:

dataflow.serviceAgent

Wenn Sie Dataflow zum ersten Mal verwenden, weist der Dienst Ihnen diese Rolle zu. Sie müssen diese Berechtigung dann also nicht erteilen.

Standardmäßig wird das Compute Engine-Dienstkonto für Launcher-VMs und Worker-VMs verwendet. Das Dienstkonto benötigt die folgenden Rollen und Funktionen:

Storage-Objekt-Administrator (roles/storage.objectAdmin)
Betrachter (roles/viewer)
Dataflow-Worker (roles/dataflow.worker)
Lese- und Schreibzugriff auf den Staging-Bucket
Lesezugriff auf das Flex-Vorlagenbild

Wenn Sie Lese- und Schreibzugriff auf den Staging-Bucket gewähren möchten, verwenden Sie die Rolle "Storage-Objekt-Administrator" (roles/storage.objectAdmin). Weitere Informationen finden Sie unter IAM-Rollen für Cloud Storage.

Um Lesezugriff auf das Flex-Vorlagen-Image zu erteilen, können Sie die Rolle "Storage-Objekt-Betrachter" (roles/storage.objectViewer) verwenden. Weitere Informationen erhalten Sie unter Zugriffssteuerung konfigurieren.

Erforderliche Dockerfile-Umgebungsvariablen festlegen

Wenn Sie ein eigenes Dockerfile für einen Flex-Vorlagenjob erstellen möchten, geben Sie die folgenden Umgebungsvariablen an:

Java

Geben Sie FLEX_TEMPLATE_JAVA_MAIN_CLASS und FLEX_TEMPLATE_JAVA_CLASSPATH im Dockerfile an.

ENV	Beschreibung	Erforderlich
`FLEX_TEMPLATE_JAVA_MAIN_CLASS`	Gibt an, welche Java-Klasse zum Starten der Flex-Vorlage ausgeführt wird.	JA
`FLEX_TEMPLATE_JAVA_CLASSPATH`	Gibt den Speicherort der Klassendateien an.	JA
`FLEX_TEMPLATE_JAVA_OPTIONS`	Gibt die Java-Optionen an, die beim Starten der Flex-Vorlage übergeben werden sollen.	NEIN

Python

Geben Sie FLEX_TEMPLATE_PYTHON_PY_FILE im Dockerfile an.

Legen Sie zum Verwalten von Pipelineabhängigkeiten Variablen in Ihrem Dockerfile fest, z. B.:

FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
FLEX_TEMPLATE_PYTHON_PY_OPTIONS
FLEX_TEMPLATE_PYTHON_SETUP_FILE
FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES

Die folgenden Umgebungsvariablen werden beispielsweise in der Anleitung zum Streaming in einer Python-Flex-Vorlage in GitHub festgelegt:

ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="${WORKDIR}/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/streaming_beam.py"

ENV	Beschreibung	Erforderlich
`FLEX_TEMPLATE_PYTHON_PY_FILE`	Gibt an, welche Python-Datei zum Starten der Flex-Vorlage ausgeführt werden soll.	JA
`FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE`	Gibt die Anforderungsdatei mit Pipeline-Abhängigkeiten an. Weitere Informationen finden Sie unter PyPI-Abhängigkeiten in der Apache Beam-Dokumentation.	NEIN
`FLEX_TEMPLATE_PYTHON_SETUP_FILE`	Gibt den Pfad zur Datei „setup.py“ des Pipelinepakets an. Weitere Informationen finden Sie in der Apache Beam-Dokumentation unter Mehrere Dateiabhängigkeiten.	NEIN
`FLEX_TEMPLATE_PYTHON_EXTRA_PACKAGES`	Gibt die Pakete an, die nicht öffentlich verfügbar sind. Weitere Informationen zur Verwendung zusätzlicher Pakete finden Sie unter Lokale oder Nicht-PyPI-Abhängigkeiten.	NEIN
`FLEX_TEMPLATE_PYTHON_PY_OPTIONS`	Gibt die Python-Optionen an, die beim Starten der Flex-Vorlage übergeben werden sollen.	NEIN

Paketabhängigkeiten

Wenn eine Dataflow-Python-Pipeline zusätzliche Abhängigkeiten verwendet, müssen Sie möglicherweise die Flex-Vorlage so konfigurieren, dass zusätzliche Abhängigkeiten auf Dataflow-Worker-VMs installiert werden.

Wenn Sie einen Python-Dataflow-Job ausführen, der Flex-Vorlagen in einer Umgebung verwendet, die den Zugriff auf das Internet einschränkt, müssen Sie die Abhängigkeiten beim Erstellen der Vorlage vorab verpacken.

Verwenden Sie eine der folgenden Optionen, um die Python-Abhängigkeiten vorab zu verpacken.

Eine Anleitung zum Verwalten von Pipelineabhängigkeiten in Java- und Go-Pipelines finden Sie unter Pipelineabhängigkeiten in Dataflow verwalten.

Anforderungsdatei verwenden und Abhängigkeiten mit der Vorlage vorab verpacken

Wenn Sie ein eigenes Dockerfile zum Definieren des Flex-Vorlagen-Images verwenden, führen Sie die folgenden Schritte aus:

Erstellen Sie eine requirements.txt-Datei, in der Ihre Pipelineabhängigkeiten aufgelistet sind.

COPY requirements.txt /template/
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"

Installieren Sie die Abhängigkeiten im Flex-Vorlagen-Image.

RUN pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

Laden Sie die Abhängigkeiten in den lokalen Anforderungs-Cache herunter, der den Dataflow-Workern beim Start der Vorlage bereitgestellt wird.
```
RUN pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE
```

Bei diesem Ansatz werden Abhängigkeiten aus der requirements.txt-Datei zur Laufzeit auf Dataflow-Workern installiert. In einer Statistik auf dem Tab "Empfehlungen" der Google Cloud Console kann dieses Verhalten angezeigt werden. Verwenden Sie ein benutzerdefiniertes Container-Image, um die Installation von Abhängigkeiten zur Laufzeit zu vermeiden.

Das folgende Codebeispiel verwendet eine Anforderungsdatei in der Flex-Vorlage.

# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

FROM gcr.io/dataflow-templates-base/python3-template-launcher-base

# Configure the Template to launch the pipeline with a --requirements_file option.
# See: https://beam.apache.org/documentation/sdks/python-pipeline-dependencies/#pypi-dependencies
ENV FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE="/template/requirements.txt"
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/streaming_beam.py"

COPY . /template

RUN apt-get update \
    # Install any apt packages if required by your template pipeline.
    && apt-get install -y libffi-dev git \
    && rm -rf /var/lib/apt/lists/* \
    # Upgrade pip and install the requirements.
    && pip install --no-cache-dir --upgrade pip \
    # Install dependencies from requirements file in the launch environment.
    && pip install --no-cache-dir -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE \
    # When FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE  option is used,
    # then during Template launch Beam downloads dependencies
    # into a local requirements cache folder and stages the cache to workers.
    # To speed up Flex Template launch, pre-download the requirements cache
    # when creating the Template.
    && pip download --no-cache-dir --dest /tmp/dataflow-requirements-cache -r $FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE

# Set this if using Beam 2.37.0 or earlier SDK to speed up job submission.
ENV PIP_NO_DEPS=True

ENTRYPOINT ["/opt/google/dataflow/python_template_launcher"]

Pipeline als Paket strukturieren und lokale Pakete verwenden

Wenn Sie mehrere lokale Python-Dateien oder ‑Module verwenden, strukturieren Sie Ihre Pipeline als Paket. Die Dateistruktur könnte so aussehen:

main.py
pyproject.toml
setup.py
src/
  my_package/
    my_custom_dofns_and_transforms.py
    my_pipeline_launcher.py
    other_utils_and_helpers.py

Platzieren Sie den Einstiegspunkt der obersten Ebene, z. B. die Datei main.py, im Stammverzeichnis. Legen Sie die restlichen Dateien in einem separaten Ordner im Verzeichnis src ab, z. B. my_package.

Fügen Sie dem Stammverzeichnis die Paketkonfigurationsdateien mit den Paketdetails und ‑anforderungen hinzu.

pyproject.toml

[project]
name = "my_package"
version = "package_version"
dependencies = [
  # Add list of packages (and versions) that my_package depends on.
  # Example:
  "apache-beam[gcp]==2.54.0",
]

setup.py

  """An optional setuptools configuration stub for the pipeline package.

  Use pyproject.toml to define the package. Add this file only if you must
  use the --setup_file pipeline option or the
  FLEX_TEMPLATE_PYTHON_SETUP_FILE configuration option.
  """

  import setuptools
  setuptools.setup()

Weitere Informationen zum Konfigurieren Ihres lokalen Pakets finden Sie unter Paket für Python-Projekte erstellen.

Verwenden Sie beim Importieren lokaler Module oder Dateien für Ihre Pipeline den Paketnamen my_package als Importpfad.
```
from my_package import word_count_transform
```

Installieren Sie das Pipelinepaket im Image für flexible Vorlagen. Ihr Dockerfile für flexible Vorlagen kann Inhalte enthalten, die dem folgenden Beispiel ähneln:

Dockerfile

ENV FLEX_TEMPLATE_PYTHON_PY_FILE="${WORKDIR}/main.py"
ENV FLEX_TEMPLATE_PYTHON_SETUP_FILE="${WORKDIR}/setup.py"

# Copy pipeline, packages and requirements.
WORKDIR ${WORKDIR}
COPY main.py .
COPY pyproject.toml .
COPY setup.py .
COPY src src

# Install local package.
RUN pip install -e .

Ein Beispiel für diesen Ansatz finden Sie in der Anleitung Flexible Vorlage für eine Pipeline mit Abhängigkeiten und einem benutzerdefinierten Container-Image in GitHub.

Benutzerdefinierten Container verwenden, der alle Abhängigkeiten vorinstalliert

Verwenden Sie benutzerdefinierte Container, um die Installation von Abhängigkeiten zur Laufzeit zu vermeiden. Diese Option wird für Pipelines bevorzugt, die in Umgebungen ohne Internetzugriff ausgeführt werden.

So verwenden Sie einen benutzerdefinierten Container:

Erstellen Sie ein Image für benutzerdefinierte Container, der erforderliche Abhängigkeiten vorinstalliert.
Installieren Sie dieselben Abhängigkeiten im Dockerfile der Flex-Vorlage.

Verwenden Sie in der Konfiguration der flexiblen Vorlage nicht die Optionen FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE oder FLEX_TEMPLATE_PYTHON_SETUP_FILE, um die Installation von Abhängigkeiten zur Laufzeit zu verhindern.

Eine geänderte flexible Vorlage Dockerfile könnte so aussehen wie in folgendem Beispiel:
```
FROM gcr.io/dataflow-templates-base/python3-template-launcher-base
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/main.py"
COPY . /template
# If you use a requirements file, pre-install the requirements.txt.
RUN pip install --no-cache-dir -r /template/requirements.txt
# If you supply the pipeline in a package, pre-install the local package and its dependencies.
RUN pip install -e /template
```
Bei diesem Ansatz gehen Sie so vor:
- Image für flexible Vorlagen erstellen
- Benutzerdefiniertes SDK-Container-Image erstellen
- In beiden Images dieselben Abhängigkeiten installieren
Alternativ können Sie Ihr benutzerdefiniertes Container-Image als Basis-Image für die flexible Vorlage verwenden, um die Anzahl der zu verwaltenden Images zu reduzieren.
Wenn Sie das Apache Beam SDK in Version 2.49.0 oder niedriger verwenden, fügen Sie die Pipelineoption --sdk_location=container in Ihrem Pipeline-Launcher hinzu. Mit dieser Option wird Ihre Pipeline angewiesen, das SDK aus dem benutzerdefinierten Container zu verwenden, anstatt das SDK herunterzuladen.
```
options = PipelineOptions(beam_args, save_main_session=True, streaming=True, sdk_location="container")
```

Legen Sie im Befehl flex-template run den Parameter sdk_container_image fest. Beispiel:

gcloud dataflow flex-template run $JOB_NAME \
   --region=$REGION \
   --template-file-gcs-location=$TEMPLATE_PATH \
   --parameters=sdk_container_image=$CUSTOM_CONTAINER_IMAGE \
   --additional-experiments=use_runner_v2

Weitere Informationen finden Sie unter Benutzerdefinierte Container in Dataflow verwenden.

Basis-Image auswählen

Sie können ein von Google bereitgestelltes Basis-Image verwenden, um Ihre Container-Images aus Vorlagen mithilfe von Docker zu verpacken. Wählen Sie in den Basis-Images für Flex-Vorlagen das neueste Tag aus. Es wird empfohlen, ein konkretes Image-Tag anstelle von latest zu verwenden.

Geben Sie das Basis-Image im folgenden Format an:

gcr.io/dataflow-templates-base/IMAGE_NAME:TAG

Ersetzen Sie dabei Folgendes:

IMAGE_NAME ist ein von Google bereitgestelltes Basis-Image
TAG: Versionsname für das Basis-Image in der Referenz zu Basis-Images für Flex-Vorlagen

Benutzerdefinierte Container-Images verwenden

Wenn die Pipeline ein benutzerdefiniertes Container-Image verwendet, sollten Sie dieses als Basis-Image für das Docker-Image der Flex-Vorlage verwenden. Kopieren Sie dazu die Launcher-Binärdatei der Flex-Vorlage aus dem von Google bereitgestellten Vorlagen-Basis-Image in Ihr benutzerdefiniertes Image.

Ein Beispiel-Dockerfile für ein Image, das sowohl als benutzerdefiniertes SDK-Container-Image als auch als flexible Vorlage verwendet werden kann, könnte so aussehen:

FROM gcr.io/dataflow-templates-base/IMAGE_NAME:TAG as template_launcher
FROM apache/beam_python3.10_sdk:2.59.0

# RUN <...Make image customizations here...>
# See: https://cloud.google.com/dataflow/docs/guides/build-container-image

# Configure the Flex Template here.
COPY --from=template_launcher /opt/google/dataflow/python_template_launcher /opt/google/dataflow/python_template_launcher
COPY my_pipeline.py /template/
ENV FLEX_TEMPLATE_PYTHON_PY_FILE="/template/my_pipeline.py"

Ersetzen Sie dabei Folgendes:

IMAGE_NAME: Ein von Google bereitgestelltes Basis-Image Beispiel: python311-template-launcher-base.
TAG: Versions-Tag für das Basis-Image in der Referenz zu Basis-Images für Flex-Vorlagen Zur Gewährleistung der Stabilität und zur Fehlerbehebung sollten Sie latest nicht verwenden. Nutzen Sie stattdessen ein konkretes Versions-Tag.

Ein Beispiel für diesen Ansatz finden Sie in der Anleitung Flex-Vorlage für eine Pipeline mit Abhängigkeiten und einem benutzerdefinierten Container-Image.

Image aus einer privaten Registry verwenden

Sie können ein Flex-Vorlagen-Image erstellen, das in einer privaten Docker-Registry gespeichert ist, wenn die private Registry HTTPS verwendet und ein gültiges Zertifikat hat.

Wenn Sie ein Image aus einer privaten Registry verwenden möchten, geben Sie den Pfad zum Image sowie einen Nutzernamen und ein Passwort für die Registry an. Der Nutzername und das Passwort müssen im Secret Manager gespeichert werden. Sie können das Secret in einem der folgenden Formate angeben:

projects/{project}/secrets/{secret}/versions/{secret_version}
projects/{project}/secrets/{secret}

Wenn Sie das zweite Format nutzen, verwendet Dataflow die neueste Version, da es keine Version festlegt.

Wenn die Registry ein selbst signiertes Zertifikat verwendet, müssen Sie auch den Pfad zum selbst signierten Zertifikat in Cloud Storage angeben.

In der folgenden Tabelle werden die Optionen der gcloud-Befehlszeile erläutert, mit denen Sie eine private Registry konfigurieren können.

Parameter	Beschreibung
`image`	Die Adresse der Registry. Beispiel: `gcp.repository.example.com:9082/registry/example/image:latest`.
`image-repository-username-secret-id`	Die geheime Secret Manager-ID für den Nutzernamen zur Authentifizierung bei der privaten Registry. Beispiel: `projects/example-project/secrets/username-secret`.
`image-repository-password-secret-id`	Die geheime ID des Secret Managers für das Passwort zur Authentifizierung bei der privaten Registry. Beispiel: `projects/example-project/secrets/password-secret/versions/latest`.
`image-repository-cert-path`	Die vollständige Cloud Storage-URL für ein selbst signiertes Zertifikat für die private Registry. Dies ist nur erforderlich, wenn die Registry ein selbst signiertes Zertifikat verwendet. Beispiel: `gs://example-bucket/self-signed.crt`.

Hier sehen Sie ein Beispiel für einen Google Cloud CLI-Befehl, der eine Flex-Vorlage mit einem Image in einer privaten Registry mit einem selbst signierten Zertifikat erstellt.

gcloud dataflow flex-template build gs://example-bucket/custom-pipeline-private-repo.json
--sdk-language=JAVA
--image="gcp.repository.example.com:9082/registry/example/image:latest"
--image-repository-username-secret-id="projects/example-project/secrets/username-secret"
--image-repository-password-secret-id="projects/example-project/secrets/password-secret/versions/latest"
--image-repository-cert-path="gs://example-bucket/self-signed.crt"
--metadata-file=metadata.json

Zum Erstellen einer eigenen Flex-Vorlage müssen Sie die Beispielwerte ersetzen und möglicherweise andere oder zusätzliche Optionen angeben. Weitere Informationen finden Sie in folgenden Dokumenten:

Pipelineoptionen angeben

Informationen zu Pipelineoptionen, die direkt von Flex-Vorlagen unterstützt werden, erhalten Sie unter Pipelineoptionen.

Sie können auch alle Apache Beam-Pipelineoptionen indirekt verwenden. Wenn Sie für Ihren Flex-Vorlagenjob eine metadata.json-Datei verwenden, nehmen Sie diese Pipelineoptionen in die Datei auf. Diese Metadatendatei muss das Format in TemplateMetadata haben.

Andernfalls übergeben Sie beim Starten des Flex-Vorlagenjobs diese Pipelineoptionen mit dem Parameterfeld.

API

Fügen Sie Pipelineoptionen mit dem Feld parameters hinzu.

gcloud

Fügen Sie Pipelineoptionen mit dem Flag parameters hinzu.

Wenn Sie Parameter vom Typ List oder Map übergeben, müssen Sie möglicherweise Parameter in einer YAML-Datei definieren und flags-file verwenden. Ein Beispiel für diesen Ansatz finden Sie im Schritt "Datei mit Parametern erstellen..." in dieser Lösung.

Bei Verwendung von Flex-Vorlagen haben Sie die Möglichkeit, einige Pipelineoptionen bei der Pipelineinitialisierung zu konfigurieren. Es können aber nicht alle Pipelineoptionen geändert werden. Wenn die von der Flex-Vorlage erforderlichen Befehlszeilenargumente überschrieben werden, kann es sein, dass der Job die vom Vorlagen-Launcher übergebenen Pipelineoptionen ignoriert, überschreibt oder verwirft. Der Job wird möglicherweise nicht gestartet, oder es wird ein Job gestartet, der die Flex-Vorlage nicht verwendet. Weitere Informationen finden Sie unter Jobdatei konnte nicht gelesen werden.

Ändern Sie bei der Pipelineinitialisierung die folgenden Pipelineoptionen nicht:

Java

runner
project
jobName
templateLocation
region

Python

runner
project
job_name
template_location
region

Go

runner
project
job_name
template_location
region

Projekt-SSH-Schlüssel für VMs mit metadatenbasierten SSH-Schlüsseln blockieren

Wenn Sie verhindern möchten, dass VMs SSH-Schlüssel akzeptieren, die in Projektmetadaten gespeichert sind, können Sie die Projekt-SSH-Schlüssel für VMs blockieren. Verwenden Sie das Flag additional-experiments mit der Dienstoption block_project_ssh_keys:

--additional-experiments=block_project_ssh_keys

Weitere Informationen finden Sie unter Dataflow-Dienstoptionen.

Metadaten

Sie können Ihre Vorlage um zusätzliche Metadaten erweitern, damit benutzerdefinierte Parameter bei der Ausführung der Vorlage überprüft werden. Wenn Sie Metadaten für Ihre Vorlage erstellen möchten, gehen Sie so vor:

Erstellen Sie eine metadata.json-Datei mit den Parametern unter Metadatenparameter.
Ein Beispiel finden Sie unter Beispiel-Metadatendatei.
Speichern Sie die Metadatendatei in Cloud Storage im selben Ordner wie die Vorlage.

Metadatenparameter

Parameterschlüssel		Erforderlich	Beschreibung des Werts
`name`		Ja	Der Name Ihrer Vorlage.
`description`		Nein	Ein kurzer Textabschnitt, der die Vorlage beschreibt.
`streaming`		Nein	Wenn `true`, unterstützt diese Vorlage das Streaming. Der Standardwert ist `false`.
`supportsAtLeastOnce`		Nein	Wenn `true`, unterstützt diese Vorlage die mindestens einmalige Verarbeitung. Der Standardwert ist `false`. Setzen Sie diesen Parameter auf `true`, wenn die Vorlage für den "Mindestens einmal"-Streamingmodus ausgelegt ist.
`supportsExactlyOnce`		Nein	Bei `true` unterstützt diese Vorlage die genau einmalige Verarbeitung. Der Standardwert ist `true`.
`defaultStreamingMode`		Nein	Den Standard-Streamingmodus für Vorlagen, die sowohl den "Mindestens einmal"-Modus als auch den "Genau einmal"-Modus unterstützen. Verwenden Sie einen der folgenden Werte: `"AT_LEAST_ONCE"`, `"EXACTLY_ONCE"`. Wenn keine Angabe gemacht wird, wird der Standard-Streamingmodus "genau einmal" verwendet.
`parameters`		Nein	Ein Array von zusätzlichen Parametern, die die Vorlage verwendet. Ein leeres Array wird standardmäßig verwendet.
	`name`	Ja	Der Name des Parameters, der in Ihrer Vorlage verwendet wird.
	`label`	Ja	Ein für Menschen lesbarer String, der in der Google Cloud Console verwendet wird, um den Parameter mit einem Label zu versehen.
	`helpText`	Ja	Ein kurzer Textabschnitt, der den Parameter beschreibt.
	`isOptional`	Nein	`false`, wenn der Parameter erforderlich ist, und `true`, wenn der Parameter optional ist. Sofern kein Wert festgelegt ist, wird für `isOptional` standardmäßig der Wert `false` verwendet. Wenn Sie diesen Parameterschlüssel nicht für Ihre Metadaten angeben, werden die Metadaten zu einem erforderlichen Parameter.
	`regexes`	Nein	Ein Array von regulären POSIX-egrep-Ausdrücken in Stringform, die verwendet werden, um den Wert des Parameters zu validieren. Beispiel: `["^[a-zA-Z][a-zA-Z0-9]+"]` ist ein einzelner regulärer Ausdruck, der validiert, dass der Wert mit einem Buchstaben beginnt und dann ein oder mehrere Zeichen enthält. Ein leerer Array wird standardmäßig verwendet.

Beispiel-Metadatendatei

Java

{
  "name": "Streaming Beam SQL",
  "description": "An Apache Beam streaming pipeline that reads JSON encoded messages from Pub/Sub, uses Beam SQL to transform the message data, and writes the results to a BigQuery",
  "parameters": [
    {
      "name": "inputSubscription",
      "label": "Pub/Sub input subscription.",
      "helpText": "Pub/Sub subscription to read from.",
      "regexes": [
        "[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "outputTable",
      "label": "BigQuery output table",
      "helpText": "BigQuery table spec to write to, in the form 'project:dataset.table'.",
      "isOptional": true,
      "regexes": [
        "[^:]+:[^.]+[.].+"
      ]
    }
  ]
}

Python

{
  "name": "Streaming beam Python flex template",
  "description": "Streaming beam example for python flex template.",
  "parameters": [
    {
      "name": "input_subscription",
      "label": "Input PubSub subscription.",
      "helpText": "Name of the input PubSub subscription to consume from.",
      "regexes": [
        "projects/[^/]+/subscriptions/[a-zA-Z][-_.~+%a-zA-Z0-9]{2,}"
      ]
    },
    {
      "name": "output_table",
      "label": "BigQuery output table name.",
      "helpText": "Name of the BigQuery output table name.",
      "isOptional": true,
      "regexes": [
        "([^:]+:)?[^.]+[.].+"
      ]
    }
  ]
}

Sie können Metadatendateien für die von Google bereitgestellten Vorlagen aus dem Vorlagenverzeichnis von Dataflow herunterladen.

Informationen zum Staging-Speicherort und temporären Speicherort

Google Cloud CLI bietet die Optionen --staging-location und --temp-location, wenn Sie eine flexible Vorlage ausführen. In ähnlicher Weise stellt die Dataflow REST API die Felder stagingLocation und tempLocation für FlexTemplateRuntimeEnvironment bereit.

Bei Flex-Vorlagen ist der Staging-Speicherort die Cloud Storage-URL, in die Dateien während des Staging-Schritts beim Starten einer Vorlage geschrieben werden. Dataflow liest diese bereitgestellten Dateien, um die Vorlagengrafik zu erstellen. Der temporäre Speicherort ist die Cloud Storage-URL, in die während des Ausführungsschritts temporäre Dateien geschrieben werden.

Job mit flexibler Vorlage aktualisieren

Die folgende Beispielanfrage zeigt, wie Sie eine Vorlage für einen Streamingjob mit der Methode projects.locations.flexTemplates.launch aktualisieren. Wenn Sie die gcloud CLI verwenden möchten, finden Sie weitere Informationen unter Vorhandene Pipeline aktualisieren.

Wenn Sie eine klassische Vorlage aktualisieren möchten, verwenden Sie stattdessen projects.locations.templates.launch.

Führen Sie die Schritte zum Erstellen eines Streamingjobs aus einer flexiblen Vorlage aus. Senden Sie die folgende HTTP-POST-Anfrage mit den geänderten Werten:
```
POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/flexTemplates:launch
{
    "launchParameter": {
      "update": true
      "jobName": "JOB_NAME",
      "parameters": {
        "input_subscription": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_NAME",
        "output_table": "PROJECT_ID:DATASET.TABLE_NAME"
      },
    "containerSpecGcsPath": "STORAGE_PATH"
    },
}
```
- Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID.
- Ersetzen Sie REGION durch die Dataflow-Region des Jobs, den Sie aktualisieren.
- Ersetzen Sie JOB_NAME durch den genauen Namen des Jobs, den Sie aktualisieren möchten.
- Stellen Sie das Flag parameters auf Ihre Liste der Schlüssel/Wert-Paare ein. Die aufgeführten Parameter gelten speziell für dieses Vorlagenbeispiel. Wenn Sie eine benutzerdefinierte Vorlage verwenden, ändern Sie die Parameter nach Bedarf. Wenn Sie die Beispielvorlage verwenden, ersetzen Sie die folgenden Variablen.
  - Ersetzen Sie SUBSCRIPTION_NAME durch den Namen des Pub/Sub-Abos.
  - Ersetzen Sie DATASET durch den Namen Ihres BigQuery-Datasets.
  - Ersetzen Sie TABLE_NAME durch Ihren BigQuery-Tabellennamen.
- Ersetzen Sie STORAGE_PATH durch den Cloud Storage-Speicherort der Vorlagendatei. Der Speicherort sollte mit gs:// beginnen.
Mit dem Parameter environment können Sie die Umgebungseinstellungen ändern. Weitere Informationen finden Sie unter: FlexTemplateRuntimeEnvironment
Optional: Zum Senden der Anfrage mit curl (Linux, macOS oder Cloud Shell) speichern Sie die Anfrage in einer JSON-Datei und führen Sie dann den folgenden Befehl aus:
```
curl -X POST -d "@FILE_PATH" -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)"  https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/flexTemplates:launch
```
Ersetzen Sie FILE_PATH durch den Pfad zur JSON-Datei, die den Anfragetext enthält.
Überprüfen Sie über die Dataflow-Monitoring-Oberfläche, ob ein neuer Job mit demselben Namen erstellt wurde. Dieser Job hat den Status Aktualisiert.

Beschränkungen

Die folgenden Einschränkungen gelten für flexible Vorlagenjobs:

Sie müssen ein von Google bereitgestelltes Basis-Image verwenden, um Ihre Container mit Docker zu packen. Eine Liste der anwendbaren Images finden Sie unter Flex-Vorlagen-Images.
Das Programm, das die Pipeline erstellt, muss nach dem Aufruf von run beendet werden, damit die Pipeline gestartet werden kann.
waitUntilFinish (Java) und wait_until_finish (Python) werden nicht unterstützt.

Wie geht es weiter?

Weitere Informationen zu klassischen Vorlagen und Flex-Vorlagen sowie zu ihren Anwendungsfallszenarien finden Sie unter Dataflow-Vorlagen.
Informationen zur Fehlerbehebung bei flexiblen Vorlagen finden Sie unter Fehlerbehebung bei Zeitüberschreitungen bei Flex-Vorlagen.
Weitere Referenzarchitekturen, Diagramme und Best Practices finden Sie im Cloud-Architekturcenter.