Laufzeitargumente in einer Ausführungsanfrage übergeben

Mit Workflows können Sie dynamische Eingaben für eine Ausführung mithilfe von Laufzeitargumenten bereitstellen, auf die Ihr Workflow über Variablen zugreift. So können Sie die Ausführungslogik anpassen und unterschiedliche Ereignisnutzlasten verarbeiten, ohne die Workflowdefinition zu ändern.

Workflow einrichten, der Laufzeitargumente empfängt

So richten Sie einen Workflow ein, um Laufzeitargumente zu empfangen, die Sie ihm im Rahmen einer Ausführungsanfrage übergeben:

  1. Folgen Sie der Anleitung zum Erstellen eines neuen Workflows oder wählen Sie einen vorhandenen Workflow zum Aktualisieren aus, stellen Sie ihn aber noch nicht bereit.

  2. Fügen Sie der Definition des Hauptworkflows das Feld params hinzu. Achten Sie darauf, dass der Argumentname in eckigen Klammern steht und der Hauptworkflow in einem main-Block platziert ist:

    YAML

    main:
  params: [ARG_NAME]
  steps:
    ...

    JSON

    {
  "main": {
    "params": ["ARG_NAME"],
    "steps": [
      ...
    ]
    ...
  }
}

    Der Block main akzeptiert ein einzelnes Argument, das der Name eines beliebigen gültigen JSON-Datentyps ist, z. B. ein Array, ein Objekt oder ein String.

    Als Best Practice empfiehlt es sich, ein Objekt mit mehreren benannten Argumenten zu übergeben, da so der Zweck der Argumente leichter nachvollziehbar ist und Argumente einfacher hinzugefügt werden können. Anschließend können Sie mit der Punktnotation auf die Argumente zugreifen.

    Andere Unterarbeitsabläufe können mehrere Argumente haben.

    Der folgende Workflow gibt beispielsweise eine "Hello"-Begrüßung an eine Person zurück, deren Vor- und Nachname als Laufzeitargumente übergeben wird:

    YAML

    main:
  params: [args]
  steps:
    - step1:
        assign:
          - outputVar: ${"Hello, " + args.firstName + " " + args.lastName + "!"}
    - step2:
        return: ${outputVar}

    JSON

    {
  "main": {
    "params": [
      "args"
    ],
    "steps": [
      {
        "step1": {
          "assign": [
            {
              "outputVar": "${\"Hello \" + args.firstName + \" \" + args.lastName}"
            }
          ]
        }
      },
      {
        "step2": {
          "return": "${outputVar}"
        }
      }
    ]
  }
}

  3. Stellen Sie Ihren Workflow bereit, um ihn zu erstellen oder zu aktualisieren.

Daten in einer Ausführungsanfrage übergeben

Sobald Ihr Workflow für den Empfang von Laufzeitargumenten eingerichtet ist, können Sie in einer Ausführungsanfrage einen String im JSON-Format, z. B. {"firstName":"Workflows","lastName":"User"}, an den Workflow übergeben.

Console

  1. Wenn Sie einen Workflow ausführen möchten, rufen Sie in der Google Cloud Console die Seite Workflows auf:

    Zur Seite "Workflows"

  2. Wählen Sie auf der Seite Workflows einen Workflow aus, um die zugehörige Detailseite aufzurufen.

  3. Klicken Sie auf der Seite Workflow-Details auf Ausführen.

  4. Geben Sie auf der Seite "Workflow ausführen" in den Bereich "Eingabe" einen JSON-String ein, der Ihre Parameternamen und Argumentwerte wie {"firstName":"Workflows","lastName":"User"} enthält:

    Eingabebereich mit dem JSON-Beispielstring

  5. Klicken Sie auf Ausführen.

    Auf der Seite Ausführungsdetails können Sie die Ergebnisse der Ausführung aufrufen, einschließlich der Ausgabe Hello, Workflows User!, der Ausführungs-ID und des Ausführungsstatus sowie des aktuellen oder letzten Schritts der Workflow-Ausführung. Weitere Informationen finden Sie unter Auf Workflow-Ausführungsergebnisse zugreifen.

gcloud

Fügen Sie dem Befehl gcloud workflow execute das Flag --data hinzu, das Sie zum Ausführen Ihres Workflows verwenden. Dieses Flag verwendet einen JSON-String Ihrer Daten. So übergeben Sie beispielsweise firstName und lastName an den vorherigen Beispielworkflow:

gcloud workflows run WORKFLOW_NAME \
--data='{"firstName":"FIRST","lastName":"LAST"}'

Dabei gilt:

  • WORKFLOW_NAME: der Name des Workflows
  • FIRST: Der String, den Sie für firstName an Ihren Workflow übergeben möchten
  • LAST: Der String, den Sie für lastName an Ihren Workflow übergeben möchten

Die Ausgabe sollte in etwa so aussehen:

Waiting for execution [9379b067-306a-4db1-a58d-c9fc99aebfd4] to complete...done.
argument: '{"firstName":"Workflows","lastName":"User"}'
endTime: '2022-07-19T13:52:47.659199466Z'
name: projects/1051295516635/locations/us-central1/workflows/workflow-6/executions/9379b067-306a-4db1-a58d-c9fc99aebfd4
result: '"Hello, Workflows User!"'
startTime: '2022-07-19T13:52:47.623862835Z'
state: SUCCEEDED
status:
  currentSteps:
  - routine: main
    step: step2
workflowRevisionId: 000002-138

Clientbibliotheken

Abhängig von der Sprache der Clientbibliothek können Sie ein Laufzeitargument in einer Ausführungsanfrage übergeben.

Beispiel mit JavaScript:

// Execute workflow
try {
  const createExecutionRes = await client.createExecution({
    parent: client.workflowPath(projectId, location, workflow),
    execution: {
      argument: JSON.stringify({"firstName":"Workflows","lastName":"User"})
    }
});
const executionName = createExecutionRes[0].name;

Oder mit Java:

// Creates the execution object.
CreateExecutionRequest request =
    CreateExecutionRequest.newBuilder()
        .setParent(parent.toString())
        .setExecution(Execution.newBuilder().setArgument("{\"firstName\":\"Workflows\",\"lastName\":\"User\"}").build())
        .build();

Weitere Informationen zum Ausführen eines Workflows mit den Google API-Clientbibliotheken finden Sie unter Workflow ausführen.

REST API

  1. Hängen Sie das Flag data an den Befehl an, den Sie zum Ausführen Ihres Workflows verwenden. Der Wert von data ist ein JSON-formatierter String mit einem Argument, dessen Wert ein oder mehrere Escape-Parameter-Wert-Paare ist. So übergeben Sie beispielsweise firstName und lastName an den vorherigen Beispielworkflow:

    curl --request POST \
   --header "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
   --header 'Content-Type: application/json' \
   --data '{"argument":"{\"firstName\":\"FIRST\",\"lastName\":\"LAST\"}"}' \
   "https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/workflows/WORKFLOW_NAME/executions"

    Ersetzen Sie Folgendes:

    • PROJECT_NUMBER: Ihre Google Cloud Projektnummer
    • WORKFLOW_NAME: der Name des Workflows
    • FIRST: Der String, den Sie für firstName an Ihren Workflow übergeben möchten.
    • LAST: Der String, den Sie für lastName an Ihren Workflow übergeben möchten.

    Die Ausgabe sollte in etwa so aussehen:

    {
  "name": "projects/PROJECT_NUMBER/locations/us-central1/workflows/WORKFLOW_NAME/executions/EXECUTION_ID",
  "startTime": "2020-11-09T23:51:31.765761331Z",
  "state": "ACTIVE",
  "argument": "{\"firstName\":\"Workflows\",\"lastName\":\"User\"}",
  "workflowRevisionId": "000001-08c"
}
 ```

  2. Führen Sie den folgenden Befehl aus, um die Ausführungsergebnisse abzurufen:

    curl --request GET \
   --header "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
   --header 'Content-Type: application/json' \
   "https://workflowexecutions.googleapis.com/v1/projects/PROJECT_NUMBER/locations/us-central1/workflows/WORKFLOW_NAME/executions/EXECUTION_ID"

    Ersetzen Sie EXECUTION_ID durch die ID aus der Ausgabe, die von Ihrem ersten Befehl zurückgegeben wurde.

    Diese Ausgabe enthält Zeilen, die in etwa so aussehen:

    "argument": "{\"firstName\":\"Workflows\",\"lastName\":\"User\"}",
"result": "\"Hello, Workflows User!\"",

Weitere Informationen zum Ausführen eines Workflows mit der REST API finden Sie unter Workflow ausführen.

Auf Laufzeitargumente zugreifen

In diesem Beispiel wird auf Laufzeitargumente zugegriffen, die im Rahmen der Ausführungsanfrage an den Workflow übergeben werden. Alle Argumente werden in derselben Zuordnung gespeichert, die als Parameter des Hauptworkflows deklariert sind.

Übergeben Sie bei diesem Workflow Laufzeitargumente im folgenden Format:

{"firstName":"Sherlock", "lastName":"Holmes"}

YAML

main:
  params: [args]
  steps:
    - step1:
        assign:
          - outputVar: ${"Hello " + args.firstName + " " + args.lastName}
    - step2:
        return: ${outputVar}

JSON

{
  "main": {
    "params": [
      "args"
    ],
    "steps": [
      {
        "step1": {
          "assign": [
            {
              "outputVar": "${\"Hello \" + args.firstName + \" \" + args.lastName}"
            }
          ]
        }
      },
      {
        "step2": {
          "return": "${outputVar}"
        }
      }
    ]
  }
}

Sie können default mit der Standardbibliotheksfunktion map.get verwenden, um auf optionale Laufzeitargumente zuzugreifen und einen Standardwert zurückzugeben, wenn der Schlüssel nicht gefunden wird. Wenn im folgenden Beispiel kein region angegeben ist, wird northamerica-northeast1 verwendet:

YAML

  main:
      params: [input]
      steps:
      - init:
          assign:
            - region: ${default(map.get(input, "region"), "northamerica-northeast1")}

JSON

  {
    "main": {
      "params": [
        "input"
      ],
      "steps": [
        {
          "init": {
            "assign": [
              {
                "region": "${default(map.get(input, \"region\"), \"northamerica-northeast1\")}"
              }
            ]
          }
        }
      ]
    }
  }

Nächste Schritte