Parametrisierung von Workflowvorlagen

Wenn Ihre Workflow-Vorlage mehrere Male mit unterschiedlichen Werten ausgeführt wird, können Sie Parameter in der Vorlage definieren (Vorlage parametrisieren). Auf diese Weise vermeiden Sie, den Workflow jedes Mal neu bearbeiten zu müssen. Sie können dann bei jeder neuen Ausführung der Vorlage verschiedene Werte für die Parameter übergeben.

Der Workflowvorlage können Parameter hinzugefügt werden, wenn Sie die Vorlage erstellen oder aktualisieren.

Parametrisierbare Felder

In Cloud Dataproc-Workflow-Vorlagen können folgende Felder parametrisiert werden:

• Labels
• Datei-URIs
• Name des verwalteten Clusters: Dataproc verwendet den vom Nutzer bereitgestellten Namen als Namenspräfix und hängt zufällige Zeichen an, um einen eindeutigen Clusternamen zu erstellen. Der Cluster wird am Ende des Workflows gelöscht.
• Jobattribute
• Jobargumente
• Skriptvariablen (in HiveJob, SparkSqlJob und PigJob)
• Hauptklasse (in HadoopJob und SparkJob)
• Zone (in ClusterSelector)
• Anzahl der Instanzen (numInstances) in einer Master- oder Worker-Instanzgruppe

Mit der Parametrisierung von Labels für die Clusterauswahl können Sie den Cluster auswählen, in dem der Workflow jedes Mal ausgeführt wird, wenn Sie den Workflow ausführen (siehe Clusterauswahl mit Workflows verwenden).

Parameter-Attribute

Die Parameter für Workflow-Vorlagen werden mit den folgenden erforderlichen und optionalen Attributen definiert:

name (erforderlich)

Ein Variablenname im Unix-Format. Dieser Name wird als Schlüssel verwendet, wenn Sie später einen Wert für den Parameter angeben.

fields (erforderlich)

Eine Liste der Felder, die dieser Parameter ersetzt. Unter Parametrisierbare Felder finden Sie eine Liste der Felder, die parametrisiert werden können. Jedes Feld wird als "Feldpfad" angegeben. Unter Feldpfad-Syntax finden Sie die Syntax, die zum Angeben eines Feldpfads verwendet wird. Beachten Sie dabei, dass ein Feld nur in der Feldpfad-Liste von höchstens einem Parameter vorkommen darf.

description (optional)

Kurze Beschreibung des Parameters.

validation (optional)

Regeln zur Validierung von Parameterwerten:

1. Eine Liste zulässiger Werte
   
2. Eine Liste regulärer Ausdrücke, mit denen ein Wert übereinstimmen muss

Feldpfad-Syntax

Die Syntax eines Felds entspricht in etwa derjenigen einer FieldMask. Beispielsweise wird ein Feldpfad, der auf das Zonenfeld der Clusterauswahl einer Workflow-Vorlage verweist, als placement.clusterSelector.zone angegeben.

Feldpfade können auf Felder mit der folgenden Syntax verweisen:

• Name des verwalteten Clusters:

  • placement.managedCluster.clusterName

• Werte in Zuordnungen können mit einem Schlüssel ("key") referenziert werden. Beispiel:
  

  • labels['key']
  • placement.clusterSelector.clusterLabels['key']
  • placement.managedCluster.labels['key']
  • jobs['step-id'].labels['key']

• Jobs in der Jobliste können mit einer Schritt-ID ("step-id") referenziert werden. Beispiel:
  

  • jobs['step-id'].hadoopJob.mainJarFileUri
  • jobs['step-id'].hiveJob.queryFileUri
  • jobs['step-id'].pySparkJob.mainPythonFileUri
  • jobs['step-id'].hadoopJob.jarFileUris[0]
  • jobs['step-id'].hadoopJob.archiveUris[0]
  • jobs['step-id'].hadoopJob.fileUris[0]

  • jobs['step-id'].pySparkJob.pythonFileUris[0]

  • Elemente in wiederkehrenden Feldern können mit einem nullbasierten Index referenziert werden. Beispiel:
    

  • jobs['step-id'].sparkJob.args[0]

  • Weitere Beispiele:

  • jobs['step-id'].hadoopJob.args[0]

  • jobs['step-id'].hadoopJob.mainJarFileUri

  • jobs['step-id'].hadoopJob.properties['Schlüssel']

  • jobs['step-id'].hiveJob.scriptVariables['Schlüssel']

  • placement.clusterSelector.zone

Zuordnungen und wiederkehrende Felder können nicht in ihrer Gesamtheit parametrisiert werden. Derzeit können nur einzelne Zuordnungswerte und Elemente in wiederkehrenden Feldern referenziert werden. Die folgenden Feldpfade sind beispielsweise ungültig:

placement.clusterSelector.clusterLabels
jobs['step-id'].sparkJob.args

Workflow-Vorlage parametrisieren

Sie parametrisieren eine Workflow-Vorlage, indem Sie Vorlagenparameter mit der Dataproc API oder der Google Cloud CLI definieren.

gcloud-Befehl

Sie können Parameter für Workflow-Vorlagen definieren, indem Sie eine YAML-Datei für Workflow-Vorlagen erstellen oder mit der Google Cloud CLI exportieren und bearbeiten. Anschließend importieren Sie die Datei mit der Google Cloud CLI, um die Vorlage zu erstellen oder zu aktualisieren. Weitere Informationen finden Sie unter YAML-Dateien verwenden.

Beispiel 1: Beispiel einer parametrisierten Vorlage für einen verwalteten Cluster

Im Folgenden sehen Sie eine Beispiel-YAML-Datei für einen managed-cluster-Workflow mit teragen-terasort und vier definierten Parametern: CLUSTER, NUM_ROWS, GEN_OUT und SORT_OUT. Es werden zwei Versionen aufgelistet: eine VOR und eine NACH der Parametrisierung.

Vor

placement:
  managedCluster:
    clusterName: my-managed-cluster
    config:
      gceClusterConfig:
        zoneUri: us-central1-a
jobs:
- hadoopJob:
    args:
    - teragen
    - '10000'
    - hdfs:///gen/
    mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
  stepId: teragen
- hadoopJob:
    args:
    - terasort
    - hdfs:///gen/
    - hdfs:///sort/
    mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
  prerequisiteStepIds:
  - teragen
  stepId: terasort

Nach

placement:
  managedCluster:
    clusterName: 'to-be-determined'
    config:
      gceClusterConfig:
        zoneUri: us-central1-a
jobs:
- hadoopJob:
    args:
    - teragen
    - '10000'
    - hdfs:///gen/
    mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
  stepId: teragen
- hadoopJob:
    args:
    - terasort
    - hdfs:///gen/
    - hdfs:///sort/
    mainJarFileUri: file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar
  prerequisiteStepIds:
  - teragen
  stepId: terasort
parameters:
- description: The managed cluster name prefix
  fields:
  - placement.managedCluster.clusterName
  name: CLUSTER
- description: The number of rows to generate
  fields:
  - jobs['teragen'].hadoopJob.args[1]
  name: NUM_ROWS
  validation:
    values:
      values:
      - '1000'
      - '10000'
      - '100000'
- description: Output directory for teragen
  fields:
  - jobs['teragen'].hadoopJob.args[2]
  - jobs['terasort'].hadoopJob.args[1]
  name: GEN_OUT
  validation:
    regex:
      regexes:
      - hdfs:///.*
- description: Output directory for terasort
  fields:
  - jobs['terasort'].hadoopJob.args[2]
  name: SORT_OUT
  validation:
    regex:
      regexes:
      - hdfs:///.*

Beispiel 2: Beispiel einer Workflow-Vorlage für einen Cluster-Selektor

Im Folgenden sehen Sie eine Beispiel-YAML-Datei für eine parametrisierte cluster-selector-Vorlage mit teragen-terasort und drei definierten Parametern: CLUSTER, NUM_ROWS und OUTPUT_DIR.

placement:
  clusterSelector:
    clusterLabels:
      goog-dataproc-cluster-name: 'to-be-determined'
jobs:
  - stepId: teragen
    hadoopJob:
      args:
      - 'teragen'
      - 'tbd number of rows'
      - 'tbd output directory'
parameters:
- name: CLUSTER
  fields:
  - placement.clusterSelector.clusterLabels['goog-dataproc-cluster-name']
- name: NUM_ROWS
  fields:
  - jobs['teragen'].hadoopJob.args[1]
- name: OUTPUT_DIR
  fields:
  - jobs['teragen'].hadoopJob.args[2]

Nachdem Sie eine YAML-Datei erstellt oder bearbeitet haben, die eine Workflow-Vorlage mit Vorlagenparametern definiert, importieren Sie die YAML-Datei mit dem folgenden gcloud-Befehl, um die parametrisierte Vorlage zu erstellen oder zu aktualisieren.

gcloud dataproc workflow-templates import template-ID or template-name \
    --region=region \
    --source=template.yaml

Sie können entweder die WorkflowTemplate id oder die vollständig qualifizierte Vorlagenressource name ("projects/projectId/regions/region/workflowTemplates/template_id") an den Befehl übergeben. Wenn eine Vorlagenressource mit demselben Vorlagennamen vorhanden ist, wird sie überschrieben (aktualisiert) und die zugehörige Versionsnummer wird erhöht. Wenn keine Vorlage mit demselben Vorlagennamen vorhanden ist, wird sie erstellt.

Derzeit ist es nicht möglich, mit der Google Cloud CLI einen Workflow direkt über eine YAML-Datei auszuführen, die eine parametrisierte Workflow-Vorlage definiert. Weitere Informationen finden Sie unter Workflow mithilfe einer YAML-Datei instanziieren. Sie müssen zuerst die YAML-Datei importieren und dann Parameter an die Workflow-Vorlage übergeben, wenn Sie diese instanziieren. Eine Beschreibung hierzu finden Sie in diesem und den nachfolgenden Unterabschnitten.

Rest-API

Sie können einen oder mehrere WorkflowTemplate.parameters in einer API-Anfrage workflowTemplates.create oder workflowTemplates.update definieren.

Im Folgenden finden Sie eine workflowTemplates.create-Beispielanfrage zum Erstellen einer Workflow-Vorlage mit teragen-terasort und vier definierten Parametern: CLUSTER, NUM_ROWS, GEN_OUT und SORT_OUT.

POST https://dataproc.googleapis.com/v1/projects/my-project/locations/us-central1/workflowTemplates
{
  "id": "my-template",
  "jobs": [
    {
      "stepId": "teragen",
      "hadoopJob": {
        "mainJarFileUri": "file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar",
        "args": [
          "teragen",
          "10000",
          "hdfs:///gen/"
        ]
      }
    },
    {
      "stepId": "terasort",
      "prerequisiteStepIds": [
        "teragen"
      ],
      "hadoopJob": {
        "mainJarFileUri": "file:///usr/lib/hadoop-mapreduce/hadoop-mapreduce-examples.jar",
        "args": [
          "terasort",
          "hdfs:///gen/",
          "hdfs:///sort/"
        ]
      }
    }
  ],
  "parameters": [
    {
      "name": "CLUSTER",
      "fields": [
        "placement.managedCluster.clusterName"
      ],
      "description": "The managed cluster name prefix"
    },
    {
      "name": "NUM_ROWS",
      "fields": [
        "jobs['teragen'].hadoopJob.args[1]"
      ],
      "description": "The number of rows to generate",
      "validation": {
        "values": {
          "values": [
            "1000",
            "10000",
            "100000"
          ]
        }
      }
    },
    {
      "name": "GEN_OUT",
      "fields": [
        "jobs['teragen'].hadoopJob.args[2]",
        "jobs['terasort'].hadoopJob.args[1]"
      ],
      "description": "Output directory for teragen",
      "validation": {
        "regex": {
          "regexes": [
            "hdfs:///.*"
          ]
        }
      }
    },
    {
      "name": "SORT_OUT",
      "fields": [
        "jobs['terasort'].hadoopJob.args[2]"
      ],
      "description": "Output directory for terasort",
      "validation": {
        "regex": {
          "regexes": [
            "hdfs:///.*"
          ]
        }
      }
    }
  ],
  "placement": {
    "managedCluster": {
      "clusterName": "to-be-determined",
      "config": {
        "gceClusterConfig": {
          "zoneUri": "us-central1-a"
        }
      }
    }
  }
}

Parameter an eine parametrisierte Vorlage übergeben

Bei jeder Ausführung einer parametrisierten Workflow-Vorlage können Sie einen unterschiedlichen Satz von Parameterwerten übergeben. Sie müssen für JEDEN in der Vorlage definierten Parameter einen Wert bereitstellen.

gcloud-Befehl

Sie können eine Zuordnung von Parameternamen zu Werten mit dem Flag --parameters an den Befehl gcloud dataproc workflow-templates instantiate übergeben. Alle in der Vorlage definierten Parameterwerte müssen angegeben werden. Die angegebenen Werte überschreiben die in der Vorlage angegebenen Werte.

Beispiel für eine parametrisierte Vorlage für verwaltete Cluster

gcloud dataproc workflow-templates instantiate my-template \
    --region=region \
    --parameters=CLUSTER=cluster,NUM_ROWS=1000,GEN_OUT=hdfs:///gen_20180601/,SORT_OUT=hdfs:///sort_20180601

Beispiel für eine parametrisierte Vorlage für Cluster-Selektoren

gcloud dataproc workflow-templates instantiate \
  --parameters CLUSTER=my-cluster,NUM_ROWS=10000,OUTPUT_DIR=hdfs://some/dir
    

Rest-API

Sie können eine parameters-Zuordnung des Parameters names zu values an die Dataproc API workflowTemplates.instantiate übergeben. Alle in der Vorlage definierten Parameterwerte müssen angegeben werden. Die angegebenen Werte überschreiben die in der Vorlage angegebenen Werte.

Mit der workflowTemplates.instantiateinline API können Sie keine Parameter an eine parametrisierte Workflow-Vorlage übergeben.

Example:

POST https://dataproc.googleapis.com/v1/projects/my-project/regions/us-central1/workflowTemplates/my-template:instantiate
{
  "parameters": {
    "CLUSTER": "clusterA",
    "NUM_ROWS": "1000",
    "GEN_OUT": "hdfs:///gen_20180601/",
    "SORT_OUT": "hdfs:///sort_20180601/"
  }
}