HTTP リクエストを行う

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

注: HTTP リクエストによる Google Cloud サービスの呼び出しと、Workflowsのコネクタを使用した他の Google Cloud プロダクトとワークフローを統合する API オペレーションの実行を混同しないでください。

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

次のステップ

• Cloud Run と Cloud Run 関数で Workflows を使用するチュートリアル
• VPC Service Controls 準拠のプライベート エンドポイントを呼び出す
• IAP を有効にして、プライベート オンプレミス、Compute Engine、GKE、その他のエンドポイントを呼び出す
• Workflows 構文リファレンス