invoke

Utilizza la politica invoke per richiamare una API.

Supporto gateway

Limitazione: non è possibile memorizzare nella cache una richiesta che include l'intestazione della richiesta Authorization .

Tabella 1. Tabella che mostra quali gateway supportano questa politica e la versione della politica corrispondente
Gateway	Versione politica
DataPower® Gateway (v5 compatible)	1.0.0
DataPower API Gateway	2.0.0 2.1.0 (DataPower API Gateway Versione 10.0.1.1 o successiva) 2.2.0 (DataPower API Gateway Versione 10.0.2.0 o successiva) 2.3.0 ( DataPower API Gateway Versione 10.0.3.0 o successiva)

Questo argomento descrive come configurare il criterio nella tua origine OpenAPI ; per i dettagli su come configurare il criterio nell'interfaccia utente dell'assembly, consulta Richiama.

Informazioni

La politica invoke ha il formato seguente:

- invoke:
  version: version
  title: title
  description: description
  target-url: URL_of_target_API
  backend-type: how_payload_is_sent_to_backend
  tls-profile: TLS_profile_to_be_used
  verb: method_type
  timeout: timeout_value_in_seconds
  compression: is_data_to_be_compressed
  username: username_if_authentication_required
  password: password_if_authentication_required
  output: location_of_the_invoke_result
  cache-key: unique_identifier_of_the_document_cache_entry
  cache-response: cache_behavior
  cache-putpost-response: response_caching_behavior
  cache-ttl: cache_time_to_live
  inject-proxy-headers: are_proxy_headers_sent_to_target_url
  decode-request-params: are_request_parameters_decoded
  encode-plus-char: are_plus_characters_encoded
  keep-payload: is_payload_sent_on_delete
  use-http-10: are_transactions_restricted_to_http_1.0
  chunked-uploads: are_chunked_encoded_documents_sent_to_the_server
  persistent-connection: are_persistent_connections_enabled
  header-control:
        .
        .
        .
    headers_to_copy_to_target_url
        .
        .
        .
  parameter-control:
        .
        .
        .
    parameters_to_copy_to_target_url
        .
        .
        .
  follow-redirects: url_redirection_behavior
  stop-on-error: errors_that_stop_the_flow

Proprietà

La seguente tabella descrive le proprietà della politica di richiamo.

Tabella 2. Richiamare le proprietà della politica
Proprietà	Obbligatorio	Descrizione	Tipo di dati
version	Sì	Il numero di versione della politica	stringa
title	No	Un titolo per la politica.	stringa
description	No	Una descrizione della politica.	stringa
target-url	Sì	L' URL dell'API di destinazione. Nota: Non aggiungere manualmente parametri di percorso o di query al campo target-url nel criterio di invocazione. Se questi parametri sono definiti nell'operazione API, API Connect li inietta nella destinazione URL in fase di esecuzione. Evitate di aggiungere manualmente valori come `$(request.search)` o segmenti di percorso, perché ciò potrebbe causare duplicazioni o URL malformati. Utilizzare il criterio `parameter-control` per gestire l'inclusione dei parametri di query.	stringa
backend-type	No	Specificare uno dei seguenti valori per determinare come il payload viene inviato al backend: `detect`: rileva il tipo di messaggio e invia il payload al backend di conseguenza. `xml`: impacchetta il payload come XML e invia. Se il tipo di messaggio non è XML, l'operazione ha esito negativo. `json`: impacchetta il payload come JSON e invia. Se il tipo di messaggio non è JSON, l'operazione non riesce. `binary`: impacchetta il payload come binario e invia, indipendentemente dal tipo di messaggio. `graphql`: impacchetta il payload come GraphQL e invia. Se il tipo di messaggio non lo è GraphQL, l'operazione fallisce. Il valore predefinito è `detect`.	stringa
graphql-send-type(politica versione 2.2.0 e successive)	Sì, se backend-type è impostato su `graphql` o `detect`, e verb è impostato su `POST` o `keep`.	Specificare uno dei seguenti valori per stabilire come il payload GraphQL viene inviato al backend: `detect`: rileva il tipo di messaggio e invia il payload al backend di conseguenza. `graphql`: impacchetta il payload come GraphQL e invia. Se il tipo di messaggio non lo è GraphQL, l'operazione fallisce. `json`: impacchetta il payload come JSON e invia. Se il tipo di messaggio non lo è GraphQL, l'operazione fallisce. Nota: graphql-send-type è supportato solo se backend-type è impostato su `graphql` o `detect`e verb è impostato su `POST` o `keep`.	stringa
tls-profile	No	Specifica un profilo TLS da utilizzare per la trasmissione sicura dei dati. Nota: se vuoi modificare la API nella vista di origine, assicurati che il valore tls-profile segua questo formato name:version. Ad esempio, dovrebbe essere simile a nameofmytlsclientprofile:1.0.0.	stringa
verb	No	Il tipo di metodo dell'operazione. Valori validi: GET POST PUT ELIMINA PATCH HEAD OPZIONI Il valore predefinito è `GET`. Tuttavia, se la proprietà viene omessa dall'origine, viene utilizzato il metodo HTTP della richiesta in arrivo.	stringa
timeout	No	Il tempo di attesa prima di una risposta dall'endpoint (in secondi). Il valore predefinito è `60`.	intero
http-version (versione politica 2.1.0 e successive)	Sì	La versione HTTP che verrà utilizzata per la connessione al server backend. Valori validi: `HTTP/1.0` `HTTP/1.1` `HTTP/2`	stringa
http2-required (versione politica 2.1.0 e successive)	No	Impostare questa proprietà su `true` per richiedere che il server selezioni HTTP/2 durante una connessione TLS, altrimenti DataPower API Gateway rifiuta la connessione e non riesce la richiesta. Per una connessione non TLS, viene registrata un'avvertenza che indica che non è possibile applicare il requisito. Questa impostazione si applica solo se http-version è impostata su `HTTP/2`.	booleano
compression	No	Specifica se i dati devono essere compressi utilizzando la compressione prima che vengano caricati. Il valore predefinito è `false`.	booleano
username	No	Il nome utente da utilizzare per l'autenticazione di base HTTP.	stringa
password	No	La password da utilizzare per l'autenticazione di base HTTP.	stringa
output	No	Il nome di una variabile che verrà utilizzata per archiviare i dati della risposta. Per impostazione predefinita, la risposta di chiamata, ovvero il corpo, le intestazioni, statusCode E statusMessage, viene salvato nella variabile `Messaggio`. Utilizzare questa proprietà per specificare un'ubicazione alternativa in cui memorizzare la risposta di richiamo. Questa variabile può essere referenziata in altre azioni, come ad esempio la mappa. Nota: se si desidera salvare la risposta nel `messaggio`, lasciare la proprietà output vuota, non fornire il valore `message`.	stringa
cache-key	No	Specifica l'identificativo univoco della voce cache del documento.	stringa
websocket-upgrade (versione politica 2.1.0 e successive)	No	Impostare questa proprietà su `true` per consentire l'aggiornamento di una connessione HTTP o HTTPS al protocollo WebSocket se la richiesta ricevuta dal gestore HTTP o HTTPS corrispondente su DataPower API Gateway utilizza WebSocket (ws) o WebSocket Secure (wss). Nota: Questa proprietà è disponibile solo per le API GraphQL . La proprietà `websocket-upgrade` è obsoleta. Per consentire le richieste di aggiornamento WebSocket che possono gestire i dati di elaborazione API, definisci una politica di aggiornamento WebSocket dell'assembly. Per ulteriori informazioni, vedere websocket-upgrade.	booleano
cache-response	No	Il tipo di risposta della cache. Valori validi: `protocol`: il comportamento della memoria cache è definito dalle intestazioni Cache - Control sulla richiesta e risposta. `no-cache`: specifica che non è presente alcuna memorizzazione nella cache. Tuttavia, se il documento si trova già nella cache, il documento viene richiamato dalla cache. `time-to-live`: specifica che la risposta rimane nella cache per il periodo di tempo specificato. Il valore predefinito è `protocol`.	stringa
cache-putpost-response	No	Specifica se memorizzare nella cache la risposta dalle richieste POST e PUT. La memorizzazione nella cache della risposta dalle richieste POST e PUT può ridurre il caricamento del server e la latenza nella risposta alla richiesta client. Il valore predefinito è `false`.	booleano
cache-ttl	No	Specifica la quantità di tempo, in secondi, in cui la risposta rimane nella cache. Si applica solo se la proprietà cache-response è impostata su `time-to-live`. Immettere un valore compreso tra 5 e 31708800. Il valore predefinito è `900`. Nota: Quando gli utenti accedono utilizzando il percorso di login del Toolkit (un URL che include `?from=TOOLKIT`), la chiave API generata ha un time-to-live (TTL) fisso di 5 minuti.	intero
inject-proxy-headers	No	Quando è impostata su true, la politica `invoke` inserisce le intestazioni `X-Forwarded-For`, `X-Forwarded-To`, `X-Forwarded-Host`e `X-Forwarded-Proto` nella richiesta inviata al`target-url`. Il valore predefinito è `false`.	booleano
decode-request-params	No	Se impostato su true, tutti i parametri della richiesta che sono referenziati da una definizione di variabile in `target-url` del criterio di invocazione sono URL. Il valore predefinito è `false`.	booleano
encode-plus-char	No	Quando è impostato su true, tutti i caratteri "+" nei valori del parametro di query di `target-url` sono codificati in %2F. Il valore predefinito è `false`.	booleano
keep-payload	No	Se impostato su true, la politica di richiamo invia un payload su un metodo `HTTP DELETE` . Il valore predefinito è `false`.	booleano
use-http-10 (solo versione della politica 2.0.0 )	No	Quando è impostato su true, le transazioni HTTP sono limitate alla versione 1.0. Il valore predefinito è `false`.	booleano
chunked-uploads	No	Se si imposta questa proprietà su `true`, i documenti codificati in blocchi vengono inviati al server. Quando si utilizza il protocollo HTTP 1.1, il corpo del documento può essere delimitato dalla codifica `Content-Length` o chunked. Mentre tutti i server possono interpretare `Content-Length`, molte applicazioni non riescono a comprendere i documenti codificati in blocchi. Per questo motivo, `Content-Length` è il metodo standard. L'utilizzo di `Content-Length` interferisce con la capacità di DataPower Gateway di eseguire il flusso completo. Se è necessario inviare documenti completi al server di destinazione, abilitare questa proprietà. Se abilitato, il server deve essere compatibile con RFC 2616. A differenza di tutte le altre funzioni HTTP 1.1 che possono essere negoziate in fase di esecuzione, è necessario sapere in precedenza se il server di destinazione è compatibile con la RFC 2616. Il valore predefinito è `true`. Nota: la codifica Chunked non è supportata dal protocollo HTTP 1.0.	booleano
persistent-connection (versione della politica 2.3.0 e successive)	No	Impostare questa proprietà su `true` per abilitare le connessioni persistenti HTTP, consentendo il riutilizzo della connessione. Il valore predefinito è `true`.	booleano
`header-control: type values`	No	Specifica le intestazioni in `message.headers` che si desidera copiare nell' URL di destinazione. Se la proprietà `type` è impostata su `blocklist`, la proprietà `values` elenca le intestazioni che non si desidera copiare. Se la proprietà `values` è vuota, vengono copiate tutte le intestazioni. Se la proprietà `type` è impostata su `allowlist`, la proprietà `values` elenca le intestazioni che si desidera copiare. Gli elementi elencati nella proprietà `values` sono in formato di espressione regolare. I valori non sono sensibili al maiuscolo / minuscolo. Il valore predefinito della proprietà `header-control` è `header-control: type: blocklist values: []` Vedere esempi di controllo intestazione	oggetto
`parameter-control: type values`	No	Specifica i parametri della richiesta in arrivo che si desidera copiare nell' URL di destinazione. Se la proprietà `type` è impostata su `blocklist`, la proprietà `values` elenca i parametri che non si desidera copiare. Se la proprietà `type` è impostata su `allowlist`, la proprietà `values` elenca i parametri che si desidera copiare. Se la proprietà `values` è vuota, non viene copiato alcun parametro. Gli elementi elencati nella proprietà `values` sono in formato di espressione regolare. I valori non sono sensibili al maiuscolo / minuscolo. Il valore predefinito della proprietà `parameter-control` è `parameter-control: type: allowlist values: []` Vedere esempi di controllo parametri	oggetto
follow-redirect	No	Specifica il comportamento se il server back-end restituisce il codice di stato HTTP `301 Moved Permanently`. Se questa proprietà è impostata su `true`, il criterio `invoke` segue il reindirizzamento dell' URL effettuando un'ulteriore chiamata all' URL specificato nell'intestazione `Location` nella risposta. Se questa proprietà è impostata su `false`, `invoke` salva il codice di stato `301` e la chiamata API viene considerata completa. Nota: la proprietà `follow-redirect` è supportata solo da DataPower API Gateway. Se si utilizza DataPower Gateway (v5 compatible), `invoke` segue sempre il reindirizzamento URL; il criterio (non supportato da ) salva il codice di stato e completa la chiamata API senza seguire il reindirizzamento `proxy` (non supportata da DataPower API Gateway) salva il codice di stato `301` e completa la chiamata API senza seguire il reindirizzamento URL.	booleano
stop-on-error	No	Elencare gli errori che, se generati durante l'esecuzione della politica, causano l'arresto del flusso. Se esiste un flusso `catch` configurato per l'errore, viene attivato per gestire l'errore generato. Se viene generato un errore e non sono presenti errori specificati per la proprietà Arresta in caso di errore o se l'errore generato non è uno degli errori specificati, l'esecuzione della politica può essere completata e il flusso dell'assembly continua.	stringa

Esempio

- invoke:
    version: 2.0.0
    title: get the account status
    target-url: https://example.com/accounts/{id}?status={status}
    cache-response: time-to-live
    cache-putpost-response: true
    tls-profile: MyTLSProfile:1.0.0
    verb: POST
    timeout: 60
    compression: false 
    username: MyUser
    password: MyPassword
    stop-on-error:
      - ConnectionError
      - OperationError

`header-control` esempi

# copy all headers to the target URL

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: blocklist
      values: []

# copy all headers except X-Client-ID and Content-Type

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: blocklist
      values:
        - ^X-Client-ID$
        - ^Content-Type$

# copy no headers

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values: []

# copy only the Content-Type header

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values:
        - ^Content-Type$

`parameter-control` esempi

# copy no request parameters to the target URL

- invoke:
    target-url: http://myhost/path?storeid=3
    parameter-control:
      type: allowlist
      values: []

# append the petid parameter to the target URL
# if the incoming request is http://apigw/org/sandbox/petstore/base?petid=100&display=detailed, 
# the target URL at runtime will be http://myhost/mypath?storeid=3&petid=100

- invoke:
    target-url: http://myhost/path?storeid=3
    parameter-control:
      type: allowlist
      values:
        - ^petid$

# The API definition includes a query parameter petid.
# Incoming request: https://apigw/org/sandbox/pets?petid=123
# API Connect will automatically forward petid to the target URL at runtime.

- invoke:
    target-url: https://myhost/pets
    parameter-control:
      type: allowlist
      values:
        - ^petid$