実行リクエストでのランタイム引数渡し

ワークフロー実行リクエストでランタイム引数を渡し、ワークフロー変数を使用してこれらの引数にアクセスできます。

ランタイム引数を受け取るワークフローの設定

実行リクエストの一部として渡すランタイム引数を受け取るようにワークフローを設定するには、次の手順を実行します。

  1. 手順に沿って新しいワークフローを作成するか、既存のワークフローを選択して更新しますが、まだデプロイはしないでください。

  2. メイン ワークフローの定義に params フィールドを追加します。引数名は角かっこで囲み、メイン ワークフローを main ブロックに配置します。

    YAML

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

    JSON

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

    main ブロックは、有効な JSON データ型の名前（配列、オブジェクト、文字列など）である単一の引数を受け入れます。

    おすすめの方法として、複数の名前付き引数を使用してオブジェクトを渡すと、目的の理解や引数の追加が簡単になります。また、その後ドット表記を使用して引数にアクセスすることもできます。

    他のサブワークフローには複数の引数を指定できます。

    たとえば、次のワークフローは、ランタイムの引数として渡された姓と名の人に対する「Hello」というあいさつを返します。

    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. ワークフローをデプロイして、作成または更新を完了します。

実行リクエストでのデータ渡し

ランタイム引数を受け取るようにワークフローを設定したら、{"firstName":"Workflows","lastName":"User"} などの JSON 形式の文字列を、実行リクエストのワークフローに渡すことができます。

Console

  1. ワークフローを実行するには、Google Cloud コンソールで [Workflows] ページに移動します。

    [ワークフロー] に移動

  2. [ワークフロー] ページで、ワークフローを選択して詳細ページに移動します。

  3. [ワークフローの詳細] ページで [ 実行] を選択します。

  4. [ワークフローの実行] ページが表示されたら、パラメータ名と引数値（{"firstName":"Workflows","lastName":"User"} など）を含む JSON 文字列を [入力] 領域に入力します。

    JSON 文字列の例が入力された入力領域

  5. [実行] をクリックします。

    [実行の詳細] ページで、出力 Hello, Workflows User!、実行 ID と状態、ワークフロー実行の現在のステップまたは最後のステップを含む、実行結果を確認できます。詳細については、ワークフローの実行結果にアクセスするをご覧ください。

gcloud

ワークフローの実行に使用する gcloud workflow execute コマンドに --data フラグを追加します。このフラグは、データの JSON 文字列を取得します。たとえば、前の例のワークフローに firstName と lastName を渡すには、次のようにします。

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

以下を置き換えます。

  • WORKFLOW_NAME: ワークフローの名前
  • FIRST: ワークフローの firstName に渡す文字列
  • LAST: ワークフローの lastName に渡す文字列

出力例を以下に示します。

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

クライアント ライブラリ

クライアント ライブラリの言語によっては、実行リクエストでランタイム引数を渡すことができます。

たとえば、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;

また、Java を使用する場合は次のようにします。

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

Google API クライアント ライブラリを使用してワークフローを実行する方法については、ワークフローを実行するをご覧ください。

REST API

  1. ワークフローの実行に使用するコマンドに data フラグを追加します。data の値は、エスケープされたパラメータ値のペアを 1 つ以上含む引数を持つ JSON 形式の文字列です。たとえば、前の例のワークフローに firstName と lastName を渡すには、次のようにします。

    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"

    以下を置き換えます。

    • PROJECT_NUMBER: Google Cloud プロジェクト番号。
    • WORKFLOW_NAME: ワークフローの名前
    • FIRST: ワークフローの firstName に渡す文字列
    • LAST: ワークフローの lastName に渡す文字列

    出力例を以下に示します。

    {
  "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. 実行結果を取得するには、次のコマンドを実行します。

    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"

    EXECUTION_ID は、最初のコマンドが出力した ID に置き換えます。

    この出力には、次のような行が含まれます。

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

REST API を使用してワークフローを実行する方法については、ワークフローを実行するをご覧ください。

ランタイム引数にアクセスする

このサンプルは、実行リクエストの一部としてワークフローに渡されるランタイム引数にアクセスします。すべての引数は、同じマップに格納され、メイン ワークフローのパラメータとして宣言されます。

このワークフローを実行するときは、次の形式を使用してランタイム引数を渡します。

{"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}"
        }
      }
    ]
  }
}

default と標準ライブラリ関数の map.get を使用すると、オプションのランタイム引数にアクセスして、キーが見つからない場合にデフォルト値を返すことができます。次の例では、region が指定されていない場合、northamerica-northeast1 が使用されます。

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\")}"
              }
            ]
          }
        }
      ]
    }
  }

次のステップ