Effettuare una richiesta HTTP

Puoi definire un passaggio del flusso di lavoro che effettui una chiamata HTTP e assegni la risposta della chiamata a una variabile. Ad esempio, puoi richiamare un servizio Google Cloud come le funzioni Cloud Run o Cloud Run tramite una richiesta HTTP.

Richiamare un endpoint HTTP

Questo tipo di passaggio consente di effettuare una richiesta HTTP. Sono supportate sia le richieste HTTP che quelle HTTPS. I metodi di richiesta HTTP più comuni prevedono (ad esempio http.get) e http.post), ma puoi creare qualsiasi tipo di richiesta HTTP impostando il campo call su http.request e specificando il tipo di richiesta utilizzando il 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"
      }
    }
  ]

Sostituisci quanto segue:

  • HTTP_REQUEST: obbligatorio. Utilizza una delle seguenti opzioni per le richieste HTTP:
    • http.delete
    • http.get
    • http.patch
    • http.post
    • http.put
    • http.request
  • URL_VALUE: obbligatorio. URL a cui viene inviata la richiesta.
  • REQUEST_METHOD: obbligatorio se si utilizza il tipo di chiamata http.request. Il tipo di metodo di richiesta HTTP da utilizzare. Ad esempio:
    • GET
    • POST
    • PATCH
    • DELETE
  • REGISTERED_SERVICE: facoltativo. Un registrato Nome del servizio Service Directory nel formato projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE_NAME/services/SERVICE_NAME. Per ulteriori informazioni, vedi Richiama un Endpoint privato conforme ai Controlli di servizio VPC.
  • HEADER_KEY:HEADER_VALUE: facoltativo. Campi intestazione per fornire input all'API.

    Se utilizzi un'intestazione Content-Type per specificare tipo multimediale del corpo della richiesta, sono supportati solo i seguenti tipi:

    • application/json o application/type+json: deve essere una mappa
    • application/x-www-form-urlencoded: deve essere un formato non codificato stringa
    • text/type: deve essere una stringa

    Se viene specificata un'intestazione Content-Type, il corpo viene codificato come prescritto. Ad esempio, potrebbe essere in formato JSON o con codifica URL.

    Se utilizzi un'intestazione User-Agent per identificare che richiede lo user agent, si applica quanto segue:

    • L'impostazione predefinita è GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
    • Se viene specificato un valore, viene aggiunto GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs).

      Ad esempio, se User-Agent: "MY_USER_AGENT_VALUE" , l'intestazione della richiesta HTTP sarà la seguente (con un spazio tra il valore specificato e il valore predefinito aggiunto):

      MY_USER_AGENT_VALUE GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
  • BODY_KEY:BODY_VALUE: facoltativo. Campi del corpo per fornire l'input all'API.

    Se non viene specificata un'intestazione Content-Type e se una richiesta esistente, si applica quanto segue:

    • Se il valore del corpo è in byte, l'intestazione viene impostata su Content-Type: application/octet-stream.
    • In caso contrario, il corpo è codificato in JSON e l'intestazione è impostata su Content-Type: application/json; charset=utf-8.
    Il seguente esempio mostra una struttura del corpo equivalente a un 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: facoltativo. Esegui query sui campi per fornire input all'API.
  • AUTH_TYPE: facoltativo. Obbligatorio se l'API chiamata richiede l'autenticazione. Usa OIDC o OAuth2. Per ulteriori informazioni, vedi Rendi autenticato richieste da un flusso di lavoro.
    • AUTH_SCOPE: facoltativo. Limita l'accesso di un'applicazione all'account di un utente. Utilizza il tasto scope o scopes.

      La chiave scope supporta una stringa o un elenco di stringhe. Ad esempio:

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

      o

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

      La chiave scopes, oltre a supportare una stringa o un elenco di stringhe, supporta le stringhe separate da spazi e virgole. Ad esempio:

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

      o

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

      Per ulteriori informazioni, consulta Ambiti OAuth 2.0 per le API di Google.

    • AUDIENCE: facoltativo. Specifica il pubblico per il token OIDC. Per impostazione predefinita, è impostato sullo stesso valore di url. Tuttavia, deve essere impostato sull'URL principale del servizio. Ad esempio: https://region-project.cloudfunctions.net/hello_world.
  • TIMEOUT_IN_SECONDS: facoltativo. Durata in secondi può essere eseguita una richiesta prima di generare un'eccezione. Il massimo è 1800 secondi.
  • RESULT_VALUE: facoltativo. Nome della variabile in cui viene archiviato il risultato di una chiamata HTTP.

Accedere ai dati della risposta HTTP salvati in una variabile

Se l'intestazione Content-Type della risposta specifica un tipo di media application/json, la risposta JSON memorizzata in una variabile viene convertita automaticamente in una mappa a cui è possibile accedere.

Se necessario, modifica l'API chiamata per specificare un application/json tipo di media per l'Content-Type intestazione di risposta. Altrimenti, puoi utilizzare json.decode e text.encode per converti il corpo della risposta in una mappa. Ad esempio:

json.decode(text.encode(RESPONSE_FROM_API))

Workflows include un parser integrato per accedere a questi dati. Per accedere dei campi della risposta HTTP, utilizza la seguente sintassi:

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

Sostituisci quanto segue:

  • VARIABLE_NAME: il nome della variabile di flusso di lavoro in cui hai salvato una risposta JSON.
  • body: utilizza il campo body per accedere al corpo della risposta HTTP.
  • code: utilizza il campo code per accedere al codice di risposta HTTP.
  • headers: utilizza il campo headers per accedere alle intestazioni di risposta HTTP per nome.
  • PATH_TO_FIELD: il percorso del campo nel file JSON la risposta a cui vuoi accedere. Può essere semplicemente il nome del campo o se è nidificato all'interno di un oggetto, può avere il formato object1.object2.field.

Ad esempio, se un'API restituisce {"age":50} e un flusso di lavoro memorizza questa risposta in una variabile denominata age_response, l'esempio seguente restituisce il valore del campo age; in questo caso, 50:

age_response.body.age

Esempi

Questi esempi mostrano la sintassi.

Assegnare la risposta di una chiamata API

A meno che non inserisci un tuo termine di ricerca, questo esempio utilizza il tuo indirizzo e-mail Google Cloud località per costruire un termine di ricerca, che passa alla API Wikipedia. R viene restituito un elenco di articoli di Wikipedia correlati.

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

Creare una richiesta POST HTTP esterna

In questo esempio viene effettuata una richiesta POST a un endpoint HTTP esterno.

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

Crea una richiesta GET HTTP esterna con le intestazioni

In questo esempio viene creata una richiesta GET HTTP con un'intestazione personalizzata. Puoi anche fornire definizioni di intestazioni personalizzate quando effettui altri tipi di richieste 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}"
    }
  }
]

Utilizza OIDC per eseguire l'autenticazione quando effettui una richiesta alle funzioni di Cloud Run

In questo esempio viene effettuata una richiesta HTTP utilizzando OIDC aggiungendo una sezione auth alla Sezione args della definizione del flusso di lavoro, dopo aver specificato l'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}"
    }
  }
]

Rilevare e gestire gli errori delle richieste HTTP

Questo esempio implementa un gestore delle eccezioni personalizzato in base al codice di stato HTTP restituito dalla richiesta GET. Il flusso di lavoro rileva una potenziale eccezione restituisce un messaggio di errore predefinito. Se un'eccezione non viene riconosciuta, l'esecuzione del flusso di lavoro non riesce e viene lanciata l'eccezione restituita dalla richiesta GET. Per altri tag di errore, consulta Errori di flusso di lavoro.

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

Passaggi successivi