Hacer una solicitud HTTP

Puedes definir un paso de flujo de trabajo que haga una llamada HTTP y asignar la respuesta de la llamada a una variable. Por ejemplo, puedes invocar un Google Cloudservicio como funciones de Cloud Run o Cloud Run mediante una solicitud HTTP.

No debes confundir la invocación de un servicio Google Cloud mediante una solicitud HTTP con el uso de conectores de Workflows para realizar operaciones de API. Los conectores simplifican las llamadas a servicios porque se encargan de dar formato a las solicitudes y proporcionan métodos y argumentos para que no tengas que conocer los detalles de una API de Google Cloud .

Invocar un endpoint HTTP

Este tipo de paso te permite hacer una solicitud HTTP. Se admiten solicitudes HTTP y HTTPS. Los métodos de solicitud HTTP más habituales tienen un acceso directo de llamada (como http.get y http.post), pero puedes hacer cualquier tipo de solicitud HTTP configurando el campo call como http.request y especificando el tipo de solicitud mediante el campo method.

Nota: Workflows no admite solicitudes HTTP a los puntos de conexión basados en IP de los planos de control de clústeres de Google Kubernetes Engine (GKE). Para asegurarte de que tu flujo de trabajo funciona correctamente, debes acceder a los endpoints basados en DNS. Para obtener más información, consulta las solicitudes HTTP a GKE y el anuncio del servicio

.

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

Haz los cambios siguientes:

• HTTP_REQUEST: obligatorio. Usa una de las siguientes opciones para las solicitudes HTTP:
  • http.delete
  • http.get
  • http.patch
  • http.post
  • http.put
  • http.request
• URL_VALUE: obligatorio. URL a la que se envía la solicitud.
• REQUEST_METHOD: obligatorio si se usa el tipo de llamada http.request. El tipo de método de solicitud HTTP que se va a usar. Por ejemplo:
  • GET
  • POST
  • PATCH
  • DELETE
• REGISTERED_SERVICE: opcional. Nombre de servicio de Directorio de servicios registrado con el formato projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE_NAME/services/SERVICE_NAME. Para obtener más información, consulta Invocar un punto final privado mediante el registro de servicios de Service Directory.
• HEADER_KEY:HEADER_VALUE: opcional. Campos de encabezado para proporcionar información a la API.

  Si se usa un encabezado Content-Type para especificar el tipo de medio del cuerpo de la solicitud, solo se admiten los siguientes tipos:

  • application/json o application/type+json: debe ser un mapa
  • application/x-www-form-urlencoded: debe ser una cadena sin codificar.
  • text/type: debe ser una cadena.

  Si se especifica un encabezado Content-Type, el cuerpo se codifica según lo prescrito. Por ejemplo, puede ser JSON o estar codificado como URL.

  Si se usa un encabezado User-Agent para identificar el user-agent que realiza la solicitud, se aplican las siguientes condiciones:

  • El valor predeterminado es GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
  • Si se especifica un valor, se añade GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs) a ese valor.

    Por ejemplo, si se especifica User-Agent: "MY_USER_AGENT_VALUE", el encabezado de la solicitud HTTP sería el siguiente (con un espacio entre el valor especificado y el valor predeterminado añadido):

    MY_USER_AGENT_VALUE GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)

• BODY_KEY:BODY_VALUE: opcional. Campos del cuerpo para proporcionar información a la API.

  Si no se especifica un encabezado Content-Type y hay un cuerpo de solicitud, se aplican las siguientes condiciones:

  • Si el valor del cuerpo son bytes, el encabezado se define como Content-Type: application/octet-stream.
  • De lo contrario, el cuerpo se codifica en JSON y el encabezado se define como Content-Type: application/json; charset=utf-8.
  A continuación, se muestra un ejemplo de estructura de cuerpo equivalente a una carga útil de 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. Campos de consulta para proporcionar información a la API.
• AUTH_TYPE: opcional. Obligatorio si la API a la que se llama requiere autenticación. Usa OIDC o OAuth2. Para obtener más información, consulta el artículo Hacer solicitudes autenticadas desde un flujo de trabajo.
  • AUTH_SCOPE: opcional. Limita el acceso de una aplicación a la cuenta de un usuario. Usa la tecla scope o scopes.

    La clave scope admite una cadena o una lista de cadenas. Por ejemplo:

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

    o

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

    La clave scopes, además de admitir una cadena o una lista de cadenas, admite cadenas separadas por espacios y comas. Por ejemplo:

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

    o

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

    Para obtener más información, consulta Permisos de OAuth 2.0 para APIs de Google.

  • AUDIENCE: opcional. Especifica la audiencia del token de OIDC. De forma predeterminada, tiene el mismo valor que url. Sin embargo, debe asignarle la URL raíz de su servicio. Por ejemplo: https://region-project.cloudfunctions.net/hello_world.
• TIMEOUT_IN_SECONDS: opcional. Tiempo en segundos que se permite que se ejecute una solicitud antes de generar una excepción. El máximo es de 1800 segundos.
• RESULT_VALUE: opcional. Nombre de la variable en la que se almacena el resultado de un paso de invocación HTTP.

Acceder a los datos de respuesta HTTP guardados en una variable

Si el encabezado Content-Type de la respuesta especifica un tipo de medio application/json, la respuesta JSON almacenada en una variable se convierte automáticamente en un mapa al que se puede acceder.

Si es necesario, modifica la API a la que se llama para especificar un tipo de medio application/json para el encabezado de respuesta Content-Type. De lo contrario, puedes usar las funciones json.decode y text.encode para convertir el cuerpo de la respuesta en un mapa. Por ejemplo:

json.decode(text.encode(RESPONSE_FROM_API))

Workflows incluye un analizador sintáctico integrado para acceder a estos datos. Para acceder a los campos de la respuesta HTTP, utiliza la siguiente sintaxis:

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

Haz los cambios siguientes:

• VARIABLE_NAME: el nombre de la variable de flujo de trabajo en la que has guardado una respuesta JSON.
• body: usa el campo body para acceder al cuerpo de la respuesta HTTP.
• code: usa el campo code para acceder al código de respuesta HTTP.
• headers: usa el campo headers para acceder a los encabezados de respuesta HTTP por nombre.
• PATH_TO_FIELD: la ruta al campo de la respuesta JSON al que quieres acceder. Puede ser el nombre del campo o, si el campo está anidado en un objeto, puede tener la forma object1.object2.field.

Por ejemplo, si una API devuelve {"age":50} y un flujo de trabajo almacena esa respuesta en una variable llamada age_response, el ejemplo siguiente devuelve el valor del campo age, que en este caso es 50:

age_response.body.age

Ejemplos

En estos ejemplos se muestra la sintaxis.

Asignar la respuesta de una llamada a la API

A menos que introduzcas tu propio término de búsqueda, esta muestra usa tu Google Cloud ubicación para crear un término de búsqueda, que pasa a la API de Wikipedia. Se devuelve una lista de artículos de Wikipedia relacionados.

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

Hacer una solicitud HTTP POST externa

En este ejemplo se envía una solicitud POST a un endpoint 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}"
    }
  }
]

Hacer una solicitud GET HTTP externa con encabezados

En este ejemplo se envía una solicitud HTTP GET con un encabezado personalizado. También puede proporcionar definiciones de encabezados personalizados al hacer otros tipos de solicitudes 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}"
    }
  }
]

Usar OIDC para autenticar al hacer una solicitud a funciones de Cloud Run

En este ejemplo se envía una solicitud HTTP mediante OIDC. Para ello, se añade una sección auth a la sección args de la definición del flujo de trabajo después de especificar la 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}"
    }
  }
]

Detectar y gestionar errores de solicitudes HTTP

En este ejemplo se implementa un controlador de excepciones personalizado basado en el código de estado HTTP devuelto por la solicitud GET. El flujo de trabajo detecta una posible excepción y devuelve un mensaje de error predefinido. Si no se reconoce una excepción, la ejecución del flujo de trabajo falla y genera la excepción devuelta por la solicitud GET. Para ver otras etiquetas de error, consulta Errores de flujo de trabajo.

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

Siguientes pasos

• Tutorial sobre el uso de Workflows con Cloud Run y Cloud Run Functions
• Invocar un punto final privado mediante el registro de servicios del directorio de servicios
• Invocar un endpoint privado on-premise, de Compute Engine, de GKE o de otro tipo habilitando IAP
• Referencia de la sintaxis de Workflows