invia una richiesta HTTP

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

Nota: la chiamata a un servizio Google Cloud tramite una richiesta HTTP non deve essere confusa con l'utilizzo dei connectors Workflows per eseguire operazioni API che integrano il flusso di lavoro con altri prodotti Google Cloud.

Richiama 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 hanno una scorciatoia di chiamata (come http.get e http.post), ma puoi effettuare 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 uno dei seguenti 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 utilizzi il tipo di chiamata http.request. Il tipo di metodo di richiesta HTTP da utilizzare. Ecco alcuni esempi:
  • GET
  • POST
  • PATCH
  • DELETE
• REGISTERED_SERVICE: facoltativo. Un nome registrato del servizio Service Directory nel formato projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE_NAME/services/SERVICE_NAME. Per maggiori informazioni, consulta Richiamare 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 il 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 una stringa non codificata
  • text/type: deve essere una stringa

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

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

  • Il valore predefinito è GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs)
  • Se viene specificato un valore, GoogleCloudWorkflows; (+https://cloud.google.com/workflows/docs) viene aggiunto a questo valore

    Ad esempio, se viene specificato User-Agent: "MY_USER_AGENT_VALUE", l'intestazione della richiesta HTTP sarà la seguente (con uno 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 input all'API.

  Se non viene specificata un'intestazione Content-Type e se è presente un corpo della richiesta, si applica quanto segue:

  • Se il valore del corpo è costituito da byte, l'intestazione è impostata su Content-Type: application/octet-stream.
  • In caso contrario, il corpo sarà codificato in formato JSON e l'intestazione è impostata su Content-Type: application/json; charset=utf-8.
  L'esempio seguente riguarda 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. Campi di query per fornire input all'API.
• AUTH_TYPE: facoltativo. Obbligatorio se l'API chiamata richiede l'autenticazione. Usa OIDC o OAuth2. Per maggiori informazioni, consulta Effettuare richieste autenticate da un flusso di lavoro.
  • AUTH_SCOPE: facoltativo. Limita l'accesso di un'applicazione all'account di un utente. Usa 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"]

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

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

    o

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

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

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

Accedi ai dati delle risposte HTTP salvati in una variabile

Se l'intestazione Content-Type per la risposta specifica un tipo multimediale application/json, la risposta JSON archiviata in una variabile viene automaticamente convertita in una mappa accessibile.

Se necessario, modifica l'API chiamata per specificare un tipo multimediale application/json per l'intestazione della risposta Content-Type. Altrimenti, puoi utilizzare le funzioni json.decode e text.encode per convertire 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 ai campi dalla risposta HTTP, utilizza la seguente sintassi:

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

Sostituisci quanto segue:

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

Ad esempio, se un'API restituisce {"age":50} e un flusso di lavoro archivia la 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.

Assegna la risposta da una chiamata API

A meno che tu non inserisca un termine di ricerca, questo esempio utilizza la tua posizione Google Cloud per creare un termine di ricerca che passa all'API Wikipedia. Viene restituito un elenco di articoli correlati di 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]}"
        }
      }
    ]
  }
}

crea una richiesta POST HTTP esterna

Questo esempio invia una richiesta POST a un endpoint HTTP esterno.

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

Creazione di una richiesta HTTP GET esterna con intestazioni

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

Usa OIDC per l'autenticazione quando effettui una richiesta a Cloud Functions

Questo esempio invia 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}"
    }
  }
]

Rilevamento e gestione degli errori delle richieste HTTP

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

YAML

- 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

• Tutorial sull'utilizzo di Workflows con Cloud Run e Cloud Functions
• Richiamare un endpoint privato conforme ai Controlli di servizio VPC
• Richiamare un endpoint privato on-prem, Compute Engine, GKE o un altro endpoint abilitando IAP
• Riferimento alla sintassi di Workflows