HTTP リクエストを行う

HTTP 呼び出しを行い、そのレスポンスを変数に割り当てるワークフローステップを定義できます。たとえば、HTTP リクエストを介して Cloud Run 関数や Cloud Run などの Google Cloud サービスを呼び出すことができます。

HTTP エンドポイントの呼び出し

HTTP リクエストは、このタイプのステップを使用して行えます。リクエストは、HTTP と HTTPS の両方がサポートされています。最も一般的な HTTP リクエストメソッドには、呼び出しショートカット（http.get、http.post など）がありますが、call フィールドを http.request に設定し、method フィールドでリクエストのタイプを指定することであらゆるタイプの HTTP リクエストを作成できます。

YAML

  - STEP_NAME:
      call: HTTP_REQUEST
      args:
          url: URL_VALUE
          method: REQUEST_METHOD
          private_service_name: "REGISTERED_SERVICE"
          headers:
              HEADER_KEY:HEADER_VALUE
              ...
          body:
              BODY_KEY:BODY_VALUE
              ...
          query:
              QUERY_KEY:QUERY_VALUE
              ...
          auth:
              type: AUTH_TYPE
              scope: AUTH_SCOPE
              scopes: AUTH_SCOPE
              audience: AUDIENCE
          timeout: TIMEOUT_IN_SECONDS
      result: RESULT_VALUE

JSON

  [
    {
      "STEP_NAME": {
        "call": "HTTP_REQUEST",
        "args": {
          "url": "URL_VALUE",
          "method": "REQUEST_METHOD",
          "private_service_name": "REGISTERED_SERVICE",
          "headers": {"HEADER_KEY":"HEADER_VALUE",
          ...
          },
          "body": {"BODY_KEY":"BODY_VALUE",
          ...
          },
          "query": {"QUERY_KEY":"QUERY_VALUE",
          ...
          },
          "auth": {
            "type":"AUTH_TYPE",
            "scope":"AUTH_SCOPE",
            "scopes":"AUTH_SCOPE",
            "audience":"AUDIENCE"
          },
          "timeout": "TIMEOUT_IN_SECONDS"
        },
        "result": "RESULT_VALUE"
      }
    }
  ]

次のように置き換えます。

HTTP_REQUEST: 必須。HTTP リクエストには、次のいずれかを使用します。
- http.delete
- http.get
- http.patch
- http.post
- http.put
- http.request
URL_VALUE: 必須。リクエストの送信先 URL。
REQUEST_METHOD: 呼び出しタイプ http.request を使用する場合は必須。使用する HTTP リクエストメソッドのタイプ。例:
- GET
- POST
- PATCH
- DELETE
REGISTERED_SERVICE: 省略可。projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE_NAME/services/SERVICE_NAME の形式で登録された Service Directory サービス名。詳細については、VPC Service Controls 準拠のプライベートエンドポイントを呼び出すをご覧ください。
HEADER_KEY:HEADER_VALUE: 省略可。API への入力を与えるヘッダーフィールド。
Content-Type ヘッダーを使用してリクエスト本文のメディアタイプを指定する場合、次のタイプのみがサポートされます。
- application/json または application/type+json - マッピングにする必要があります
- application/x-www-form-urlencoded - エンコードされていない文字列にする必要があります
- text/type - 文字列にする必要があります
Content-Type ヘッダーが指定されている場合、本文は規定どおりにエンコードされます。たとえば、JSON 形式や URL エンコード形式などが考えられます。

User-Agent ヘッダーを使用してリクエストしているユーザーエージェントを識別する場合は、次が適用されます。
- デフォルト値は GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs) です。
- 値が指定されている場合、GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs) はその値に追加されます。
  たとえば、User-Agent: "MY_USER_AGENT_VALUE" が指定されている場合、HTTP リクエストヘッダーは次のようになります（指定された値と追加されたデフォルト値の間にスペースがあります）。
```
MY_USER_AGENT_VALUE GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
```

BODY_KEY:BODY_VALUE: 省略可。API への入力を与える本文フィールド。

Content-Type ヘッダーが指定されておらず、リクエスト本文が存在する場合は、次が適用されます。

本文の値がバイトの場合、ヘッダーは Content-Type: application/octet-stream に設定されます。
それ以外の場合、本文は JSON エンコードされ、ヘッダーは Content-Type: application/json; charset=utf-8 に設定されます。

次の例は、JSON ペイロードと同等の本文の構造の例です。

YAML

body:
  requests:
  - image:
      source:
        gcsImageUri: ${gsUri}
    features:
    - type: LABEL_DETECTION
    - type: SAFE_SEARCH_DETECTION
    - type: IMAGE_PROPERTIES
result: imageAnalysisResponse

JSON

{
  "requests":[
    {
      "image": {
        "source": {
            "gcsUri": "img.png"
        }
      },
      "features": [
        { "type":"LABEL_DETECTION" },
        { "type":"SAFE_SEARCH_DETECTION" },
        { "type":"IMAGE_PROPERTIES" },
      ]
    }
  ]
}

QUERY_KEY:QUERY_VALUE: 省略可。API への入力を与えるクエリフィールド。
AUTH_TYPE: 省略可。呼び出される API で認証が必要な場合は必須。OIDC または OAuth2 を使用します。詳細については、ワークフローから認証済みリクエストを行うをご覧ください。
- AUTH_SCOPE: 省略可。アプリケーションからユーザーのアカウントへのアクセスを制限します。scope または scopes 鍵を使用します。
  scope キーは、文字列または文字列のリストのいずれかをサポートします。次に例を示します。
  "https://www.googleapis.com/auth/cloud-platform"
  または
  ["https://www.googleapis.com/auth/cloud-platform", "scope2", "scope3"]
  scopes キーは、文字列または文字列のリストのサポートに加えて、スペースとカンマ区切りの文字列をサポートします。次に例を示します。
  "https://www.googleapis.com/auth/cloud-platform scope2 scope3"
  または
  "https://www.googleapis.com/auth/cloud-platform,scope2,scope3"
  詳細については、Google API の OAuth 2.0 スコープをご覧ください。
- AUDIENCE: 省略可。OIDC トークンのオーディエンスを指定します。デフォルトでは、url と同じ値に設定されています。ただし、サービスのルート URL に設定する必要があります。例: https://region-project.cloudfunctions.net/hello_world.
TIMEOUT_IN_SECONDS: 省略可。例外がスローされるまでに、リクエストを実行できる時間（秒）。最大値は 1,800 秒です。
RESULT_VALUE: 省略可。HTTP 呼び出しステップの結果が保存される変数名。

変数に保存された HTTP レスポンスデータにアクセスする

レスポンスの Content-Type ヘッダーで application/json メディアタイプが指定されている場合、変数に保存される JSON レスポンスは、アクセス可能なマップに自動的に変換されます。

必要に応じて、呼び出される API を変更し、Content-Type レスポンスヘッダーの application/json メディアタイプを指定します。それ以外の場合は、json.decode 関数と text.encode 関数を使用して、レスポンスの本文をマップに変換できます。次に例を示します。

json.decode(text.encode(RESPONSE_FROM_API))

Workflows には、このデータにアクセスするパーサーが組み込まれています。HTTP レスポンスのフィールドにアクセスするには、次の構文を使用します。

${VARIABLE_NAME.body|code|headers.PATH_TO_FIELD}

以下を置き換えます。

VARIABLE_NAME: JSON レスポンスを保存したワークフロー変数の名前。
body: HTTP レスポンスの本文には、body フィールドを使用してアクセスします。
code: HTTP レスポンスコードには、code フィールドを使用してアクセスします。
headers: HTTP レスポンスヘッダーには、headers フィールドを使用して名前でアクセスします。
PATH_TO_FIELD: アクセスする JSON レスポンス内のフィールドへのパス。このフィールドの名前を単純にすることも、フィールドがオブジェクト内にネストされている場合は object1.object2.field の形式にすることもできます。

たとえば、API が {"age":50} を返し、ワークフローがそのレスポンスを age_response という変数に格納する場合、次の例では age フィールドの値が返されます。この場合は、50 です。

age_response.body.age

サンプル

ここでは、構文の例を示します。

API 呼び出しのレスポンスを割り当てる

独自の検索キーワードを入力する場合を除き、このサンプルにより Google Cloud のロケーションを使用して検索キーワードが作成され、これが Wikipedia API に渡されます。関連する Wikipedia 記事のリストが返されます。

YAML

main:
  params: [input]
  steps:
    - checkSearchTermInInput:
        switch:
          - condition: '${"searchTerm" in input}'
            assign:
              - searchTerm: '${input.searchTerm}'
            next: readWikipedia
    - getLocation:
        call: sys.get_env
        args:
          name: GOOGLE_CLOUD_LOCATION
        result: location
    - setFromCallResult:
        assign:
          - searchTerm: '${text.split(location, "-")[0]}'
    - readWikipedia:
        call: http.get
        args:
          url: 'https://en.wikipedia.org/w/api.php'
          query:
            action: opensearch
            search: '${searchTerm}'
        result: wikiResult
    - returnOutput:
        return: '${wikiResult.body[1]}'

JSON

{
  "main": {
    "params": [
      "input"
    ],
    "steps": [
      {
        "checkSearchTermInInput": {
          "switch": [
            {
              "condition": "${\"searchTerm\" in input}",
              "assign": [
                {
                  "searchTerm": "${input.searchTerm}"
                }
              ],
              "next": "readWikipedia"
            }
          ]
        }
      },
      {
        "getLocation": {
          "call": "sys.get_env",
          "args": {
            "name": "GOOGLE_CLOUD_LOCATION"
          },
          "result": "location"
        }
      },
      {
        "setFromCallResult": {
          "assign": [
            {
              "searchTerm": "${text.split(location, \"-\")[0]}"
            }
          ]
        }
      },
      {
        "readWikipedia": {
          "call": "http.get",
          "args": {
            "url": "https://en.wikipedia.org/w/api.php",
            "query": {
              "action": "opensearch",
              "search": "${searchTerm}"
            }
          },
          "result": "wikiResult"
        }
      },
      {
        "returnOutput": {
          "return": "${wikiResult.body[1]}"
        }
      }
    ]
  }
}

外部 HTTP POST リクエストを行う

このサンプルは、外部 HTTP エンドポイントに POST リクエストを行います。

YAML

- send_message:
    call: http.post
    args:
      url: https://www.example.com/endpoint
      body:
        some_val: "Hello World"
        another_val: 123
    result: the_message
- return_value:
    return: ${the_message.body}

JSON

[
  {
    "send_message": {
      "call": "http.post",
      "args": {
        "url": "https://www.example.com/endpoint",
        "body": {
          "some_val": "Hello World",
          "another_val": 123
        }
      },
      "result": "the_message"
    }
  },
  {
    "return_value": {
      "return": "${the_message.body}"
    }
  }
]

ヘッダーを持つ外部 HTTP GET リクエストを行う

このサンプルでは、カスタムヘッダーで HTTP GET リクエストを行います。カスタムヘッダーの定義を指定することで、他の種類の HTTP リクエストを行うこともできます。

YAML

- get_message:
    call: http.get
    args:
      url: https://www.example.com/endpoint
      headers:
        Content-Type: "text/plain"
      query:
        some_val: "Hello World"
        another_val: 123
    result: the_message
- return_value:
    return: ${the_message.body}

JSON

[
  {
    "get_message": {
      "call": "http.get",
      "args": {
        "url": "https://www.example.com/endpoint",
        "headers": {
          "Content-Type": "text/plain"
        },
        "query": {
          "some_val": "Hello World",
          "another_val": 123
        }
      },
      "result": "the_message"
    }
  },
  {
    "return_value": {
      "return": "${the_message.body}"
    }
  }
]

Cloud Run 関数へリクエストする際に OIDC を使用して認証する

このサンプルでは、URL を指定した後、ワークフロー定義の args セクションに auth セクションを追加することで、OIDC を使用して HTTP リクエストを行います。

YAML

- call_my_function:
    call: http.post
    args:
      url: https://us-central1-myproject123.cloudfunctions.net/myfunc1
      auth:
        type: OIDC
      body:
        some_val: "Hello World"
        another_val: 123
    result: the_message
- return_value:
    return: ${the_message.body}

JSON

[
  {
    "call_my_function": {
      "call": "http.post",
      "args": {
        "url": "https://us-central1-myproject123.cloudfunctions.net/myfunc1",
        "auth": {
          "type": "OIDC"
        },
        "body": {
          "some_val": "Hello World",
          "another_val": 123
        }
      },
      "result": "the_message"
    }
  },
  {
    "return_value": {
      "return": "${the_message.body}"
    }
  }
]

HTTP リクエストのエラーをキャッチして処理する

このサンプルは、GET リクエストによって返された HTTP ステータスコードに基づいて、カスタム例外ハンドラを実装しています。このワークフローでは、発生する可能性がある例外をキャッチして、事前定義されたエラーメッセージを返します。例外が認識されない場合、ワークフローの実行は失敗し、GET リクエストによって返された例外がスローされます。他のエラータグについては、ワークフローエラーをご覧ください。

YAML

# Use a custom exception handler to catch exceptions and return predefined
# error messages; if the exception isn't recognized, the workflow
# execution fails and throws the exception returned by the GET request
- read_item:
    try:
      call: http.get
      args:
        url: https://example.com/someapi
        auth:
          type: OIDC
      result: API_response
    except:
      as: e
      steps:
        - known_errors:
            switch:
              - condition: ${not("HttpError" in e.tags)}
                next: connection_problem
              - condition: ${e.code == 404}
                next: url_not_found
              - condition: ${e.code == 403}
                next: auth_problem
        - unhandled_exception:
            raise: ${e}
- url_found:
    return: ${API_response.body}
- connection_problem:
    return: "Connection problem; check URL"
- url_not_found:
    return: "Sorry, URL wasn't found"
- auth_problem:
    return: "Authentication error"

JSON

[
  {
    "read_item": {
      "try": {
        "call": "http.get",
        "args": {
          "url": "https://example.com/someapi",
          "auth": {
            "type": "OIDC"
          }
        },
        "result": "API_response"
      },
      "except": {
        "as": "e",
        "steps": [
          {
            "known_errors": {
              "switch": [
                {
                  "condition": "${not(\"HttpError\" in e.tags)}",
                  "next": "connection_problem"
                },
                {
                  "condition": "${e.code == 404}",
                  "next": "url_not_found"
                },
                {
                  "condition": "${e.code == 403}",
                  "next": "auth_problem"
                }
              ]
            }
          },
          {
            "unhandled_exception": {
              "raise": "${e}"
            }
          }
        ]
      }
    }
  },
  {
    "url_found": {
      "return": "${API_response.body}"
    }
  },
  {
    "connection_problem": {
      "return": "Connection problem; check URL"
    }
  },
  {
    "url_not_found": {
      "return": "Sorry, URL wasn't found"
    }
  },
  {
    "auth_problem": {
      "return": "Authentication error"
    }
  }
]

HTTP リクエストを行う

HTTP エンドポイントの呼び出し

YAML

JSON

YAML

JSON

変数に保存された HTTP レスポンス データにアクセスする

サンプル

API 呼び出しのレスポンスを割り当てる

YAML

JSON

外部 HTTP POST リクエストを行う

YAML

JSON

ヘッダーを持つ外部 HTTP GET リクエストを行う

YAML

JSON

Cloud Run 関数へリクエストする際に OIDC を使用して認証する

YAML

JSON

HTTP リクエストのエラーをキャッチして処理する

YAML

JSON

次のステップ

変数に保存された HTTP レスポンスデータにアクセスする