Make an HTTP request

You can define a workflow step that makes an HTTP call and assign the response from the call to a variable. For example, you can invoke a Google Cloud service such as Cloud Functions or Cloud Run through an HTTP request.

Invoke an HTTP endpoint

This type of step allows you to make an HTTP request. Both HTTP and HTTPS requests are supported. The most common HTTP request methods have a call shortcut (such as http.get and http.post), but you can make any type of HTTP request by setting the call field to http.request and specifying the type of request using the method field.

YAML

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

JSON

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

Replace the following:

  • HTTP_REQUEST: required. Use one of the following for HTTP requests:
    • http.delete
    • http.get
    • http.patch
    • http.post
    • http.put
    • http.request
  • URL_VALUE: required. URL where the request is sent.
  • REQUEST_METHOD: required if using call type http.request. The type of HTTP request method to use. For example:
    • GET
    • POST
    • PATCH
    • DELETE
  • HEADER_KEY:HEADER_VALUE: optional. Header fields to supply input to the API.

    If using a Content-Type header to specify the media type of the request body, only the following types are supported:

    • application/json or application/type+json—must be a map
    • application/x-www-form-urlencoded—must be an unencoded string
    • text/type—must be a string

    If using a User-Agent header to identify the requesting user agent, the following applies:

    • The default is GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
    • If a value is specified, GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs) is appended to that value

      For example, if User-Agent: "MY_USER_AGENT_VALUE" is specified, the HTTP request header would be as follows (with a space between the specified value and the appended default):

      MY_USER_AGENT_VALUE GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
  • BODY_KEY:BODY_VALUE: optional. Body fields to supply input to the API. The structure can be equivalent to a JSON payload. For example:

    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: optional. Query fields to supply input to the API.
  • AUTH_TYPE: optional. Required if the API being called requires authentication. Use either OIDC or OAuth2. See Make authenticated requests for more information.
    • SCOPE: optional. Limits an application's access to a user's account. Can be either a string or list of strings.

      For example:

      "https://www.googleapis.com/auth/cloud-platform"

      or

      ["https://www.googleapis.com/auth/cloud-platform", "scope2", "scope3"]

      See OAuth 2.0 Scopes for Google APIs.

    • AUDIENCE: optional. Specifies the audience for the OIDC token. By default, it's set to the same value as url; however, it should be set to your service's root URL. For example: https://region-project.cloudfunctions.net/hello_world.
  • TIMEOUT_IN_SECONDS: optional. How long in seconds a request is allowed to run before throwing an exception. The maximum is 1800 seconds.
  • RESULT_VALUE: optional. Variable name where the result of an HTTP invocation step is stored.

Access HTTP response data saved in a variable

When a response of type application/json is stored in a variable, the JSON response is converted to a map you access as a response body. Workflows includes a built-in parser for accessing this data. To access the fields from the HTTP response, use the following syntax:

${VARIABLE_NAME.body|code.PATH_TO_FIELD}

Replace the following:

  • VARIABLE_NAME: the name of the workflow variable where you saved a JSON response.
  • body: use the body field to access the body of the HTTP response.
  • code: use the code field to access the HTTP response code.
  • PATH_TO_FIELD: the path to the field in the JSON response that you want to access. May be simply the name of the field, or if the field is nested inside an object, it may take the form of object1.object2.field.

For example, if an API returns {"age":50} and a workflow stores that response in a variable called age_response, the following example returns the value of the age field; in this case, 50:

age_response.body.age

Samples

These samples demonstrate the syntax.

Assign the response from an API call

This sample makes a call to a sample API. The returned day of the week is passed to the Wikipedia API. Relevant articles on Wikipedia about the current day of the week are returned.

YAML

main:
    params: [input]
    steps:
    - checkSearchTermInInput:
        switch:
            - condition: ${"searchTerm" in input}
              assign:
                - searchTerm: ${input.searchTerm}
              next: readWikipedia
    - getCurrentTime:
        call: http.get
        args:
            url: https://us-central1-workflowsample.cloudfunctions.net/datetime
        result: currentDateTime
    - setFromCallResult:
        assign:
            - searchTerm: ${currentDateTime.body.dayOfTheWeek}
    - 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"
            }
          ]
        }
      },
      {
        "getCurrentTime": {
          "call": "http.get",
          "args": {
            "url": "https://us-central1-workflowsample.cloudfunctions.net/datetime"
          },
          "result": "currentDateTime"
        }
      },
      {
        "setFromCallResult": {
          "assign": [
            {
              "searchTerm": "${currentDateTime.body.dayOfTheWeek}"
            }
          ]
        }
      },
      {
        "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]}"
        }
      }
    ]
  }
}

Make an external HTTP POST request

This sample makes a POST request to an external HTTP endpoint.

YAML

- get_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

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

Make an external HTTP GET request with headers

This sample makes an HTTP GET request with a custom header. You can also supply custom header definitions when making other types of HTTP requests.

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

Use OIDC to authenticate when making a request to Cloud Functions

This sample makes an HTTP request using OIDC by adding an auth section to the args section of the workflow's definition, after specifying the URL.

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

What's next