Inviare una richiesta HTTP

Puoi definire un passaggio del workflow che effettua una chiamata HTTP e assegnare la risposta della chiamata a una variabile. Ad esempio, puoi richiamare un Google Cloud servizio come Cloud Run Functions o Cloud Run tramite una richiesta HTTP.

La chiamata a un Google Cloud servizio tramite una richiesta HTTP non deve essere confusa con l'utilizzo dei connettori Workflows connettori per eseguire operazioni API. I connettori semplificano la chiamata ai servizi perché gestiscono la formattazione delle richieste e forniscono metodi e argomenti in modo che tu non debba conoscere i dettagli di un' Google Cloud API.

Richiamare un endpoint HTTP

Questo tipo di passaggio ti consente di effettuare una richiesta HTTP. Sono supportate sia le richieste HTTP sia HTTPS. I metodi di richiesta HTTP più comuni hanno una scorciatoia di chiamata (ad esempio 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.

Nota: Workflows non supporta le richieste HTTP agli endpoint basati su IP dei piani di controllo dei cluster Google Kubernetes Engine (GKE). Per assicurarti che il workflow funzioni come previsto, devi accedere agli endpoint basati su DNS. Per saperne di più, consulta Richieste HTTP a GKE e l' annuncio del servizio.

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. Ad esempio:
  • GET
  • POST
  • PATCH
  • DELETE
• REGISTERED_SERVICE: facoltativo. Un nome di servizio Service Directory registrato nel formato projects/PROJECT_ID/locations/LOCATION/namespaces/NAMESPACE_NAME/services/SERVICE_NAME. Per saperne di più, consulta Richiamare un endpoint privato utilizzando il registro dei servizi di Service Directory.
• HEADER_KEY:HEADER_VALUE: facoltativo. Campi di intestazione per fornire input all'API.

  Se utilizzi un'intestazione Content-Type per specificare il tipo di supporto 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 prescritto. Ad esempio, potrebbe essere JSON o codificato nell'URL.

  Se utilizzi un'intestazione User-Agent per identificare lo user agent richiedente, 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 User-Agent: "MY_USER_AGENT_VALUE" viene specificato, 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 è in byte, l'intestazione viene impostata su Content-Type: application/octet-stream.
  • In caso contrario, il corpo viene codificato in JSON e l'intestazione viene impostata su Content-Type: application/json; charset=utf-8.
  L'esempio seguente 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. Campi di query per fornire input all'API.
• AUTH_TYPE: facoltativo. Obbligatorio se l'API chiamata richiede l'autenticazione. Utilizza OIDC o OAuth2. Per saperne di più, consulta Effettua richieste autenticate da un workflow.
  • AUTH_SCOPE: facoltativo. Limita l'accesso di un'applicazione all'account di un utente. Utilizza la chiave 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 stringhe separate da spazi e 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 saperne di più, 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. Il tempo in secondi durante il quale una richiesta può essere eseguita prima di generare un'eccezione. Il valore massimo è 1800 secondi.
• RESULT_VALUE: facoltativo. Nome della variabile in cui viene memorizzato il risultato di un passaggio di chiamata HTTP.

Accedere ai dati della risposta HTTP salvati in una variabile

Se l'intestazione Content-Type della risposta specifica un tipo di supporto 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 tipo di supporto application/json per l'intestazione della risposta Content-Type. In caso contrario, puoi utilizzare le json.decode e text.encode funzioni 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 della risposta HTTP, utilizza la seguente sintassi:

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

Sostituisci quanto segue:

• VARIABLE_NAME: il nome della variabile del workflow 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 della risposta HTTP per nome.
• PATH_TO_FIELD: il percorso del campo nella risposta JSON a cui vuoi accedere. Potrebbe essere il nome del campo oppure, se il campo è nidificato all'interno di un oggetto, potrebbe assumere la forma object1.object2.field.

Ad esempio, se un'API restituisce {"age":50} e un workflow memorizza questa risposta in una variabile denominata age_response, l'esempio seguente restituisce il valore di il 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 termine di ricerca personalizzato, questo esempio utilizza la tua Google Cloud posizione per creare un termine di ricerca che viene trasmesso 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]}"
        }
      }
    ]
  }
}

Effettuare una richiesta HTTP POST esterna

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

Effettuare una richiesta GET HTTP esterna con intestazioni

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

Utilizzare OIDC per l'autenticazione quando si effettua una richiesta a Cloud Run Functions

Questo esempio effettua una richiesta HTTP utilizzando OIDC aggiungendo una sezione auth alla sezione args della definizione del workflow, 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 di eccezioni personalizzato basato sul codice di stato HTTP restituito dalla richiesta GET. Il workflow rileva una potenziale eccezione e restituisce un messaggio di errore predefinito. Se un'eccezione non viene riconosciuta, l'esecuzione del workflow non riesce e genera l'eccezione restituita dalla richiesta GET. Per altri tag di errore, consulta Errori del workflow.

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

• Utilizzare Workflows con il tutorial su Cloud Run e Cloud Run Functions
• Richiamare un endpoint privato utilizzando il registro dei servizi di Service Directory
• Richiamare un endpoint protetto da IAP
• Riferimento alla sintassi di Workflows