Fazer um pedido HTTP

Pode definir uma etapa do fluxo de trabalho que faça uma chamada HTTP e atribuir a resposta da chamada a uma variável. Por exemplo, pode invocar um Google Cloud serviço como as funções do Cloud Run ou o Cloud Run através de um pedido HTTP.

A invocação de um Google Cloud serviço através de um pedido HTTP não deve ser confundida com a utilização de conectores do Workflows para realizar operações de API. Os conetores simplificam os serviços de chamadas porque processam a formatação dos pedidos por si e fornecem métodos e argumentos para que não precise de saber os detalhes de uma Google Cloud API.

Invocar um ponto final de HTTP

Este tipo de passo permite-lhe fazer um pedido HTTP. Os pedidos HTTP e HTTPS são suportados. Os métodos de pedidos HTTP mais comuns têm um atalho de chamada (como http.get e http.post), mas pode fazer qualquer tipo de pedido HTTP definindo o campo call como http.request e especificando o tipo de pedido através do campo method.

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

Substitua o seguinte:

  • HTTP_REQUEST: obrigatório. Use uma das seguintes opções para pedidos HTTP:
    • http.delete
    • http.get
    • http.patch
    • http.post
    • http.put
    • http.request
  • URL_VALUE: obrigatório. URL para onde o pedido é enviado.
  • REQUEST_METHOD: obrigatório se usar o tipo de chamada http.request. O tipo de método de pedido HTTP a usar. Por exemplo:
    • GET
    • POST
    • PATCH
    • DELETE
  • REGISTERED_SERVICE: opcional. Um nome de serviço do diretório de serviços registado no formato projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE_NAME/services/SERVICE_NAME. Para mais informações, consulte o artigo Invocar um ponto final privado através do registo de serviços do Service Directory.
  • HEADER_KEY:HEADER_VALUE: opcional. Campos de cabeçalho para fornecer entrada à API.

    Se usar um cabeçalho Content-Type para especificar o tipo de suporte do corpo do pedido, apenas são suportados os seguintes tipos:

    • application/json ou application/type+json: tem de ser um mapa
    • application/x-www-form-urlencoded: tem de ser uma string não codificada
    • text/type: tem de ser uma string

    Se for especificado um cabeçalho Content-Type, o corpo é codificado conforme prescrito. Por exemplo, pode ser JSON ou codificado por URL.

    Se usar um cabeçalho User-Agent para identificar o agente do utilizador requerente, aplica-se o seguinte:

    • A predefinição é GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
    • Se for especificado um valor, GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs) é anexado a esse valor

      Por exemplo, se User-Agent: "MY_USER_AGENT_VALUE" for especificado, o cabeçalho do pedido HTTP seria o seguinte (com um espaço entre o valor especificado e o predefinido anexado):

      MY_USER_AGENT_VALUE GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
  • BODY_KEY:BODY_VALUE: opcional. Campos do corpo para fornecer entrada à API.

    Se não for especificado um cabeçalho Content-Type e se estiver presente um corpo do pedido, aplica-se o seguinte:

    • Se o valor do corpo for bytes, o cabeçalho é definido como Content-Type: application/octet-stream.
    • Caso contrário, o corpo é codificado em JSON e o cabeçalho é definido como Content-Type: application/json; charset=utf-8.
    O exemplo seguinte mostra uma estrutura do corpo equivalente a um payload 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: opcional. Consultar campos para fornecer entrada à API.
  • AUTH_TYPE: opcional. Obrigatório se a API que está a ser chamada requerer autenticação. Use OIDC ou OAuth2. Para mais informações, consulte o artigo Faça pedidos autenticados a partir de um fluxo de trabalho.
    • AUTH_SCOPE: opcional. Limita o acesso de uma aplicação à conta de um utilizador. Use a tecla scope ou scopes.

      A chave scope suporta uma string ou uma lista de strings. Por exemplo:

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

      ou

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

      A chave scopes, além de suportar uma string ou uma lista de strings, suporta strings separadas por espaços e vírgulas. Por exemplo:

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

      ou

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

      Para mais informações, consulte o artigo Âmbitos do OAuth 2.0 para APIs Google.

    • AUDIENCE: opcional. Especifica o público-alvo do token OIDC. Por predefinição, está definido para o mesmo valor que url. No entanto, deve ser definido para o URL raiz do seu serviço. Por exemplo: https://region-project.cloudfunctions.net/hello_world.
  • TIMEOUT_IN_SECONDS: opcional. Durante quanto tempo, em segundos, é permitido que um pedido seja executado antes de gerar uma exceção. O máximo é de 1800 segundos.
  • RESULT_VALUE: opcional. Nome da variável onde o resultado de um passo de invocação HTTP é armazenado.

Aceda aos dados de resposta HTTP guardados numa variável

Se o cabeçalho Content-Type da resposta especificar um application/json tipo de suporte, a resposta JSON armazenada numa variável é convertida automaticamente num mapa acessível.

Se necessário, modifique a API que está a ser chamada para especificar um application/json tipo de suporte para o Content-Type cabeçalho de resposta. Caso contrário, pode usar as funções json.decode e text.encode para converter o corpo da resposta num mapa. Por exemplo:

json.decode(text.encode(RESPONSE_FROM_API))

O Workflows inclui um analisador incorporado para aceder a estes dados. Para aceder aos campos da resposta HTTP, use a seguinte sintaxe:

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

Substitua o seguinte:

  • VARIABLE_NAME: o nome da variável do fluxo de trabalho onde guardou uma resposta JSON.
  • body: use o campo body para aceder ao corpo da resposta HTTP.
  • code: use o campo code para aceder ao código de resposta HTTP.
  • headers: use o campo headers para aceder aos cabeçalhos de resposta HTTP por nome.
  • PATH_TO_FIELD: o caminho para o campo na resposta JSON ao qual quer aceder. Este pode ser o nome do campo ou, se o campo estiver aninhado num objeto, pode ter a forma de object1.object2.field.

Por exemplo, se uma API devolver {"age":50} e um fluxo de trabalho armazenar essa resposta numa variável denominada age_response, o exemplo seguinte devolve o valor do campo age; neste caso, 50:

age_response.body.age

Amostras

Estes exemplos demonstram a sintaxe.

Atribua a resposta de uma chamada API

A menos que introduza o seu próprio termo de pesquisa, este exemplo usa a sua Google Cloud localização para criar um termo de pesquisa, que transmite à API Wikipedia. É devolvida uma lista de artigos relacionados da Wikipédia.

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

Faça um pedido HTTP POST externo

Este exemplo faz um pedido POST a um ponto final HTTP externo.

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

Faça um pedido HTTP GET externo com cabeçalhos

Este exemplo faz um pedido HTTP GET com um cabeçalho personalizado. Também pode fornecer definições de cabeçalhos personalizados quando faz outros tipos de pedidos 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}"
    }
  }
]

Use o OIDC para autenticar quando fizer um pedido às funções do Cloud Run

Este exemplo faz um pedido HTTP através do OIDC adicionando uma secção auth à secção args da definição do fluxo de trabalho, após especificar o 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}"
    }
  }
]

Detete e processe erros de pedidos HTTP

Este exemplo implementa um controlador de exceções personalizado com base no código de estado HTTP devolvido pelo pedido GET. O fluxo de trabalho deteta uma potencial exceção e devolve uma mensagem de erro predefinida. Se não for reconhecida uma exceção, a execução do fluxo de trabalho falha e gera a exceção devolvida pelo pedido GET. Para outras etiquetas de erro, consulte o artigo Erros de fluxo de trabalho.

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

O que se segue?