Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza
documentazione di Apigee Edge.
Cosa
Il criterio ServiceCallout consente di chiamare un altro servizio dal flusso proxy API. Tu possono effettuare callout a un servizio esterno (ad esempio a un endpoint di servizio RESTful esterno) interni (ad esempio, un proxy API nella stessa organizzazione e nello stesso ambiente).
Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni per l'utilizzo, consulta Tipi di criteri.
- In un caso d'uso esterno, crei un callout per un'API di terze parti esterna al tuo proxy. La risposta dell'API di terze parti viene analizzata e inserita nella risposta dell'API arricchendo e raggruppando i dati per gli utenti finali delle app. Puoi anche inviare una richiesta utilizzando il criterio ServiceCallout nel flusso della richiesta, poi passare le informazioni nella risposta al TargetEndpoint del proxy API.
- In un altro caso d'uso, chiami un proxy che si trova nella stessa organizzazione e nello stesso ambiente di da quello da cui stai chiamando. Ad esempio, potrebbe essere utile quando hai un proxy che offre alcune discrete funzionalità di basso livello che verranno utilizzate da uno o più altri proxy. Per Ad esempio, un proxy che espone le operazioni di creazione/lettura/aggiornamento/eliminazione con un datastore di backend potrebbe essere il proxy di destinazione per più proxy che espongono i dati ai client.
Il criterio supporta le richieste su HTTP e HTTPS.
Campioni
Chiamata locale a un proxy interno
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
In questo esempio viene creato un callout per un proxy API locale (ossia uno nella stessa organizzazione)
e l'ambiente) denominato data-manager
, specificando il relativo endpoint proxy il cui nome
è default
.
URL come variabile
<HTTPTargetConnection> <URL>http://example.com/{request.myResourcePath}</URL> </HTTPTargetConnection>
In questo esempio viene utilizzata una variabile nell'URL per compilare in modo dinamico l'URL del target. La
la parte del protocollo dell'URL, http://
, non può essere specificata da un
. Inoltre, devi utilizzare variabili separate per la porzione di dominio dell'URL e
per il resto dell'URL.
Geocodifica di Google / definisci richiesta
<ServiceCallout name="ServiceCallout-GeocodingRequest1"> <DisplayName>Inline request message</DisplayName> <Request variable="authenticationRequest"> <Set> <QueryParams> <QueryParam name="address">{request.queryparam.postalcode}</QueryParam> <QueryParam name="region">{request.queryparam.country}</QueryParam> <QueryParam name="sensor">false</QueryParam> </QueryParams> </Set> </Request> <Response>GeocodingResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>https://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>
Anziché utilizzare un criterio come il criterioAssignMessage per creare l'oggetto della richiesta, puoi
lo definiranno direttamente nel criterio ServiceCallout. In questo esempio, il criterio ServiceCallout
imposta i valori di tre parametri di ricerca passati al servizio esterno. Puoi creare un nuovo
l'intero messaggio di richiesta nel criterio ServiceCallout che specifica un payload, un tipo di codifica
ad esempio application/xml
,
intestazioni, parametri modulo ecc.
Ecco un altro esempio in cui viene effettuata la richiesta prima di raggiungere ServiceCallout .
<ServiceCallout name="ServiceCallout-GeocodingRequest2"> <Request clearPayload="false" variable="GeocodingRequest"/> <Response>GeocodingResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>https://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>
Il contenuto del messaggio di richiesta viene estratto da una variabile denominata
GeocodingRequest
(che potrebbe essere
compilata, ad esempio, da un criterioAssignMessage). Il messaggio di risposta viene assegnato
chiamata GeocodingResponse
, dove è una
disponibili per essere analizzati da un criterio ExtractVariables o tramite codice personalizzato scritto in JavaScript
o Java. Il criterio attende 30 secondi di risposta dall'API Google Geocoding prima
in timeout.
Server target di chiamata
<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout"> <DisplayName>service-callout</DisplayName> <Properties/> <Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request> <Response>myResponse</Response> <HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection> </ServiceCallout>
Questo criterio utilizza l'attributo LoadBalancer per chiamare i server di destinazione ed eseguire il bilanciamento del carico
tra di loro. In questo esempio, il carico è distribuito tra due server di destinazione denominati httpbin
e yahoo
. Per informazioni sulla configurazione dei server di destinazione per il proxy e sulla configurazione
sul bilanciamento del carico, consulta Bilanciamento del carico
server di backend.
Informazioni sulle norme relative a ServiceCallout
Esistono molti scenari in cui è possibile utilizzare un criterio ServiceCallout nel proxy API. Per Ad esempio, puoi configurare un proxy API per effettuare chiamate a un servizio esterno dati di geolocalizzazione, recensioni dei clienti, articoli del catalogo di un partner e così via.
In genere, un callout viene utilizzato con altri due criteri: AssignMessage ed ExtractVariables.
- Request: AssignMessage compila il messaggio di richiesta inviato al telecomando completamente gestito di Google Cloud.
-
Response: ExtractVariables analizza la risposta ed estrae specifiche contenuti.
La tipica composizione delle norme ServiceCallout prevede:
- CriterioAssignMessage: crea un messaggio di richiesta, compila le intestazioni HTTP e parametri di ricerca, imposta il parametro HTTP verbo e così via.
-
Criterio ServiceCallout: fa riferimento a un messaggio creato dall'AssignMessage policy, definisce un URL di destinazione per la chiamata esterna e definisce un nome per l'oggetto di risposta restituito dal servizio di destinazione.
Per migliorare le prestazioni, puoi anche memorizzare nella cache le risposte ServiceCallout, come descritto in Come faccio ad archiviare i risultati del criterio ServiceCallout nella cache? e recuperarlo dalla cache in seguito?
- Criterio ExtractVariables: in genere definisce un'espressione JSONPath o XPath che analizza il messaggio generato da ServiceCallout. Il criterio quindi imposta variabili contenenti i valori analizzati dalla Risposta di ServiceCallout.
Gestione personalizzata degli errori
Riferimento elemento
Di seguito sono riportati gli elementi e gli attributi che puoi configurare su questo criterio:
<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1"> <DisplayName>Custom label used in UI</DisplayName> <Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <Remove> <StatusCode/> <Path/> <Version/> <Verb/> </Remove> <Copy> <StatusCode/> <Path/> <Version/> <Verb/> </Copy> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <Payload/> <StatusCode/> <Path/> <Version/> <Verb/> </Set> </Request> <Response>calloutResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <URL>http://example.com</URL> <LoadBalancer/> <SSLInfo/> <Properties/> <Authentication> <HeaderName ref="{variable}">STRING</HeaderName> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> <LifetimeInSeconds ref="{variable}">3600</LifetimeInSeconds> </GoogleAccessToken> </Authentication> <Authentication> <HeaderName ref="{variable}">STRING</HeaderName> <GoogleIDToken> <Audience ref="{variable}" useTargetUrl="BOOLEAN">{hostname}</Audience> <IncludeEmail ref="{variable}">true</IncludeEmail> </GoogleIDToken> </Authentication> </HTTPTargetConnection> <LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> <Path/> </LocalTargetConnection> </ServiceCallout>
<ServiceCallout> attributi
<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
name |
Il nome interno della norma. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
false | Deprecata |
Elemento <DisplayName>
Utilizzalo in aggiunta all'attributo name
per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.
<DisplayName>Policy Display Name</DisplayName>
Predefinito |
N/A Se ometti questo elemento, viene utilizzato il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
<Request> elemento
Specifica la variabile contenente il messaggio di richiesta che viene inviato dal proxy API allo altro servizio. La variabile può essere creata da un criterio precedente nel flusso oppure puoi crearla in linea nel criterio ServiceCallout.
<Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> <Remove> <StatusCode/> <Path/> <Version/> <Verb/> </Remove> <Copy> <StatusCode/> <Path/> <Version/> <Verb/> </Copy> <Add> <Headers/> <QueryParams/> <FormParams/> </Add> <Set> <Headers/> <QueryParams/> <FormParams/> <Payload/> <StatusCode/> <Path/> <Version/> <Verb/> </Set> </Request>
La sintassi dei tag <Remove>, <Copy>, <Add> e <Set> è la stessa della AssignMessage .
Il criterio restituisce un errore se il messaggio di richiesta non può essere risolto o non è valido tipo di messaggio di richiesta.
Nell'esempio più semplice, passi una variabile contenente il messaggio di richiesta che è stato compilato in precedenza nel flusso del proxy API:
<Request clearPayload="true" variable="myRequest"/>
In alternativa, puoi compilare il messaggio di richiesta inviato al servizio esterno nel criterio ServiceCallout stesso:
<Request> <Set> <Headers> <Header name="Accept">application/json</Header> </Headers> <Verb>POST</Verb> <Payload contentType="application/json">{"message":"my test message"}</Payload> </Set> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request>
Predefinito | Se ometti l'elemento Request o uno qualsiasi dei suoi attributi, Apigee assegna
i seguenti valori predefiniti:
<Request clearPayload="true" variable="servicecallout.request"/> Esaminiamo il significato di questi valori predefiniti. Innanzitutto,
È importante conoscere questo nome predefinito se utilizzi
mascheramento dei dati: se ometti il nome della variabile,
devi aggiungere |
Presenza | Facoltativo. |
Tipo | N/D |
Attributi
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
variabile |
Nome della variabile che conterrà il messaggio di richiesta. |
servicecallout.request |
Facoltativo |
clearPayload |
Se Imposta il metodo clearPayload su false solo se il messaggio di richiesta è obbligatorio dopo ServiceCallout eseguito. |
true | Facoltativo |
<Request>/<IgnoreUnresolvedVariables> elemento
Se impostato su true, il criterio ignora eventuali errori relativi alle variabili non risolte presenti nella richiesta.
<Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request>
Predefinito | falso |
Presenza | Facoltativo |
Tipo | Booleano |
<Response> elemento
Includi questo elemento quando la logica del proxy API richiede la risposta dalla chiamata remota per per ulteriore elaborazione.
Quando è presente, questo elemento specifica il nome della variabile che conterrà il messaggio di risposta ricevuto dal servizio esterno. La risposta dal target è assegnata a la variabile solo quando l'intera risposta viene letta correttamente dal criterio. Se la chiamata remota non riesce per qualsiasi motivo, il criterio restituisce un errore.
Se questo elemento viene omesso, il proxy API non attende una risposta; Flusso proxy API
l'esecuzione continua con i passaggi successivi del flusso. Inoltre, per indicare l'ovvio, senza
Response
, la risposta dal target non è disponibile per l'elaborazione in base a
passaggi successivi e il flusso proxy non rileva in alcun modo un errore nella chiamata remota.
Un uso comune per omettere l'elemento Response
quando si utilizza ServiceCallout: per registrare
a un sistema esterno.
<Response>calloutResponse</Response>
Predefinito | NA |
Presenza | Facoltativo |
Tipo | Stringa |
<Timeout> elemento
Il tempo in millisecondi durante il quale il criterio ServiceCallout attenderà una risposta dal target. Non puoi impostare questo valore in modo dinamico in fase di runtime. Se il callout di servizio raggiunge un timeout, viene restituito un HTTP 500, il criterio ha esito negativo e il proxy API entra in uno stato di errore, descritta in Gestione degli errori.
<Timeout>30000</Timeout>
Predefinito | 55.000 millisecondi (55 secondi), l'impostazione di timeout HTTP predefinita Apigee |
Presenza | Facoltativo |
Tipo | Numero intero |
<HTTPTargetConnection> elemento
Fornisce dettagli sul trasporto come URL, TLS/SSL e proprietà HTTP. Consulta le
Riferimento alla configurazione di <TargetEndpoint>
.
<HTTPTargetConnection> <URL>http://example.com</URL> <LoadBalancer/> <SSLInfo/> <Properties/> </HTTPTargetConnection>
Predefinito | N/D |
Presenza | Obbligatorio |
Tipo | N/D |
<HTTPTargetConnection>/<Authentication> elemento
Genera Google OAuth 2.0 o token OpenID Connect rilasciati da Google per effettuare chiamate autenticate ai servizi Google e ai servizi personalizzati in esecuzione su determinati prodotti Google Cloud, come Cloud Functions e Cloud Run. L'utilizzo di questo elemento richiede i passaggi di configurazione e deployment descritti in Utilizzo dell'autenticazione Google. Con configurazione corretta, il criterio crea per te un token di autenticazione e lo aggiunge alla richiesta di servizio.
Gli elementi secondari GoogleAccessToken
e GoogleIDToken
ti consentono
configurare il criterio per generare token Google OAuth o OpenID Connect. Tu
devi scegliere uno di questi elementi secondari a seconda del tipo di servizio che vuoi chiamare.
Il criterio ServiceCallout supporta solo le chiamate a servizi basati su HTTP.
Predefinito | N/D |
Obbligatorio? | Facoltativo. |
Tipo | Tipo complesso |
Elemento principale | <HTTPTargetConnection> |
Elementi secondari | <HeaderName> <GoogleAccessToken> <GoogleIDToken>
|
L'elemento Authentication
utilizza la seguente sintassi:
Sintassi
<ServiceCallout> ... <HTTPTargetConnection> <Authentication> <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName> <GoogleAccessToken> <Scopes> <Scope>SCOPE</Scope> ... </Scopes> <!-- NOTE: The default value for LifetimeInSeconds is 3600. Change the default only if you want to limit the risk of leaked access tokens or improve performance. --> <LifetimeInSeconds ref="{variable}">INTEGER</LifetimeInSeconds> </GoogleAccessToken> --OR-- <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName> <GoogleIDToken> <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience> <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail> </GoogleIDToken> </Authentication> </HTTPTargetConnection> </ServiceCallout>
Utilizzo di GoogleAccessToken
Nell'esempio seguente viene mostrato l'elemento GoogleAccessToken
:
<Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication>
Utilizzo di GoogleIDToken
Nell'esempio seguente viene mostrato l'elemento GoogleIDToken
:
<Authentication> <GoogleIDToken> <Audience>https://httpserver0-bar.run.app</Audience> <IncludeEmail>false</IncludeEmail> </GoogleIDToken> </Authentication>
Utilizzo di HeaderName
Nell'esempio seguente viene mostrato l'elemento HeaderName
:
<Authentication> <HeaderName>X-Serverless-Authorization</HeaderName> <GoogleAccessToken> <Scopes> <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope> </Scopes> </GoogleAccessToken> </Authentication>
Utilizzo di LifetimeInSeconds
Nell'esempio seguente viene mostrato l'elemento HeaderName
:
<Authentication> <GoogleAccessToken> <Scopes> <Scope>"https://www.googleapis.com/auth/cloud-platform"</Scope> </Scopes> <LifetimeInSeconds ref="variable">3600</LifetimeInSeconds> </GoogleAccessToken> </Authentication>
Attributi
Nessuno.
Elemento secondario HeaderName
Per impostazione predefinita, quando è presente una configurazione di autenticazione, Apigee genera un portatore.
e lo inserisce nell'intestazione Authorization
del messaggio inviato al sistema di destinazione.
L'elemento HeaderName
ti consente di specificare il nome di un'intestazione diversa
il token di connessione. Questa funzionalità è particolarmente utile quando la destinazione è Cloud Run
che utilizza l'intestazione X-Serverless-Authorization
. L'intestazione Authorization
,
se presente, non viene modificato e viene inviato nella richiesta.
Predefinito | N/D |
Obbligatorio? | No |
Tipo | Stringa |
Elemento principale | <Authentication> |
Elementi secondari | Nessuno |
L'elemento HeaderName
utilizza la seguente sintassi:
Sintassi
<ServiceCallout> ... <Authentication> <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName> <GoogleAccessToken> ... </GoogleAccessToken> </Authentication> ... </ServiceCallout>
Con stringa statica
In questo esempio, il token di connessione generato viene aggiunto, per impostazione predefinita, a un'intestazione denominata X-Serverless-Authorization
che viene inviato al sistema di destinazione. L'intestazione Authorization
,
se presente, non viene modificato e viene inviato nella richiesta.
<Authentication> <HeaderName>X-Serverless-Authorization</HeaderName> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication>
Con riferimento variabile
In questo esempio, il token di connessione generato viene aggiunto, per impostazione predefinita, a un'intestazione denominata X-Serverless-Authorization
che viene inviato al sistema di destinazione. Se my-variable
ha un valore, questo viene utilizzato
anziché la stringa predefinita. L'intestazione Authorization
,
se presente, non viene modificato e viene inviato nella richiesta.
<Authentication> <HeaderName ref='my-variable'>X-Serverless-Authorization</HeaderName> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication>
Elemento secondario GoogleAccessToken
Genera token Google OAuth 2.0. per effettuare chiamate autenticate ai servizi Google. I token OAuth di Google possono essere utilizzati per chiamare molti tipi di servizi Google, come Cloud Logging e Secret Manager.
Predefinito | N/D |
Obbligatorio? | Elemento secondario GoogleAccessToken o GoogleIDToken
devono essere presenti. |
Tipo | Stringa |
Elemento principale | <Authentication> |
Elementi secondari | <Scopes> <LifetimeInSeconds> |
L'elemento GoogleAccessToken
utilizza la seguente sintassi:
Sintassi
<ServiceCallout> ... <Authentication> <GoogleAccessToken> <Scopes> <Scope>SCOPE_1</Scope> ... </Scopes> <!-- NOTE: The default value for LifetimeInSeconds is 3600. We do not recommend changing the default unless you want to limit the risk of leaked access tokens or improve performance. --> <LifetimeInSeconds ref="FLOW_VARIABLE">INTEGER</LifetimeInSeconds> </GoogleAccessToken> </Authentication> ... </ServiceCallout>
Esempio 1
Nell'esempio seguente viene mostrato l'elemento GoogleAccessToken
:
<Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication>
Esempio 2
L'esempio seguente mostra come connettersi a Secret Manager per recuperare un secret utilizzando il criterio ServiceCallout.
<ServiceCallout name="ServiceCallout-sm"> <Response>SecretManagerResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication> <URL> https://secretmanager.googleapis.com/v1/projects/project-id/secrets/secret-id </URL> </HTTPTargetConnection> </ServiceCallout>
Esempio 3
L'esempio seguente mostra come eseguire un callout a Cloud dal criterio ServiceCallout.
<ServiceCallout name="ServiceCallout-CloudRun"> <Response>CloudRunResponse</Response> <Timeout>30000</Timeout> <HTTPTargetConnection> <Authentication> <GoogleIDToken> <Audience>https://cloudrun-hostname.a.run.app/test</Audience> </GoogleIDToken> </Authentication> <URL>https://cloudrun-hostname.a.run.app/test</URL> </HTTPTargetConnection> </ServiceCallout>
Elemento secondario degli ambiti
Identifica gli ambiti da includere nel token di accesso OAuth 2.0. Per ulteriori informazioni, vedi
Ambiti OAuth 2.0 per le API di Google. Puoi aggiungere uno o più elementi secondari <Scope>
in questo elemento.
Predefinito | N/D |
Obbligatorio? | Obbligatorio |
Tipo | Stringa |
Elemento principale | <GoogleAccessToken> |
Elementi secondari | <Scope> |
Elemento secondario ambito
Specifica un ambito valido dell'API di Google. Per ulteriori informazioni, vedi Ambiti OAuth 2.0 per le API di Google.
Predefinito | N/D |
Obbligatorio? | Almeno un valore è obbligatorio. |
Tipo | Stringa |
Elemento principale | <Scopes> |
Elementi secondari | Nessuno. |
Elemento secondario LifetimeInSeconds
Specifica la durata in secondi del token di accesso.
Predefinito | 3600 |
Obbligatorio? | Facoltativo |
Tipo | Numero intero |
Elemento principale | <GoogleAccessToken> |
Elementi secondari | Nessuno. |
Elemento secondario GoogleIDToken
Genera token OpenID Connect emessi da Google per effettuare chiamate autenticate ai servizi Google.
Predefinito | N/D |
Obbligatorio? | Deve essere presente l'elemento secondario GoogleAccessToken o GoogleIDToken . |
Tipo | Stringa |
Elemento principale | <Authentication> |
Elementi secondari | <Audience> <IncludeEmail> |
L'elemento GoogleIDToken
utilizza la seguente sintassi:
Sintassi
<ServiceCallout> ... <Authentication> <GoogleIDToken> <Audience ref="{variable}" useTargetUrl="BOOLEAN">STRING</Audience> <IncludeEmail ref="{variable}">BOOLEAN</IncludeEmail> </GoogleIDToken> </Authentication> </ServiceCallout>
Esempio 1
Nell'esempio seguente viene mostrato l'elemento GoogleIDToken
:
<Authentication> <GoogleIDToken> <Audience>https://httpserver0-bar.run.app</Audience> <IncludeEmail>true</IncludeEmail> </GoogleIDToken> </Authentication>
Elemento secondario del segmento di pubblico
Il pubblico del token di autenticazione generato, ad esempio l'API o l'account che che concede l'accesso.
Se il valore di Audience
è vuoto o la variabile ref
non restituisce un valore valido e
useTargetUrl
è true
, quindi l'URL del target (escluso qualsiasi
parametri di ricerca) viene utilizzato come segmento di pubblico. Per impostazione predefinita, il valore di useTargetUrl
è false
.
<Audience>explicit-audience-value-here</Audience> or: <Audience ref='variable-name-here'/> or: <Audience ref='variable-name-here' useTargetUrl='true'/> or: <Audience useTargetUrl='true'/>
Predefinito | N/D |
Obbligatorio? | Obbligatorio |
Tipo | Stringa |
Elemento principale | <GoogleIDToken> |
Elementi secondari | Nessuno. |
Elemento secondario IncludeEmail
Se impostato su true
, il token di autenticazione generato conterrà il valore
account di servizio email
e email_verified
rivendicazioni.
Predefinito | falso |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale | <GoogleIDToken> |
Elementi secondari | Nessuno. |
<HTTPTargetConnection>/<URL> elemento
L'URL del servizio chiamato:
<HTTPTargetConnection> <URL>http://example.com</URL> </HTTPTargetConnection>
Puoi fornire una parte dell'URL in modo dinamico con una variabile. Tuttavia, la parte del protocollo l'URL http:// riportato di seguito non può essere specificato da una variabile. Nel prossimo esempio, utilizzerai una variabile per specificare il valore di una query :
<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>
In alternativa, imposta una parte del percorso dell'URL con una variabile:
<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>
Se vuoi utilizzare una variabile per specificare il dominio e la porta dell'URL, usa una sola variabile solo per il dominio e la porta e una seconda variabile per qualsiasi altra parte dell'URL:
<URL>http://{request.dom_port}/{request.resourcePath}</URL>
Predefinito | N/D |
Presenza | Obbligatorio |
Tipo | Stringa |
<HTTPTargetConnection>/<SSLInfo> elemento
La configurazione TLS/SSL al servizio di backend. Per informazioni sulla configurazione TLS/SSL, consulta Opzioni per la configurazione di TLS e "Configurazione dell'endpoint di destinazione TLS/SSL" in Riferimento alla configurazione del proxy API.
<HTTPTargetConnection> <URL>https://example.com</URL> <SSLInfo> <Enabled>true</Enabled> <ClientAuthEnabled>true</ClientAuthEnabled> <KeyStore>ref://mykeystoreref</KeyStore> ## Use of a reference is recommended <KeyAlias>myKey</KeyAlias> <TrustStore>myTruststore</TrustStore> <Ciphers/> <Protocols/> </SSLInfo> </HTTPTargetConnection>
Predefinito | N/D |
Presenza | Facoltativo |
Tipo | N/D |
<HTTPTargetConnection>/<Properties> elemento
Proprietà di trasporto HTTP al servizio di backend. Per ulteriori informazioni, vedi Riferimento per le proprietà degli endpoint.
<HTTPTargetConnection> <URL>http://example.com</URL> <Properties> <Property name="allow.http10">true</Property> <Property name="request.retain.headers"> User-Agent,Referer,Accept-Language </Property> </Properties> </HTTPTargetConnection>
Predefinito | N/D |
Presenza | Facoltativo |
Tipo | N/D |
<HTTPTargetConnection>/<LoadBalancer> elemento
Chiama uno o più server di destinazione ed esegui il bilanciamento del carico sui server. Vedi il target di chiamata di esempio di server nella sezione Esempi. Vedi anche Bilanciamento del carico tra backend server web. Vedi anche Callout server/endpoint di destinazione, che illustra i modi per chiamare i server di destinazione sia dal criterio ServiceCallout che da usando le regole di route.
<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>
Predefinito | N/D |
Presenza | Facoltativo |
Tipo | N/D |
<LocalTargetConnection> elemento
Specifica un proxy locale, ovvero un proxy nella stessa organizzazione e nello stesso ambiente, del target dei callout di servizio.
Per specificare ulteriormente il target, utilizza gli elementi <APIProxy>
e <ProxyEndpoint>
oppure l'elemento <Path>
.
<LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> <Path/> </LocalTargetConnection>
Predefinito | N/D |
Presenza | Obbligatorio |
Tipo | N/D |
<LocalTargetConnection>/<APIProxy> elemento
Il nome di un proxy API che è la destinazione di una chiamata locale. Il proxy deve essere nello stesso organizzazione e ambiente come proxy che effettua la chiamata.
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
Insieme all'elemento <APIProxy>
, includi il parametro
Elemento <ProxyEndpoint>
per specificare il nome dell'endpoint proxy che deve
essere scelto come target per la chiamata.
<LocalTargetConnection> <APIProxy/> <ProxyEndpoint/> </LocalTargetConnection>
Predefinito | N/D |
Presenza | Obbligatorio |
Tipo | Stringa |
<LocalTargetConnection>/<ProxyEndpoint> elemento
Il nome dell'endpoint proxy che deve essere la destinazione delle chiamate. Questo è un endpoint proxy in
il proxy API specificato con l'elemento <APIProxy>
.
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
Predefinito | N/D |
Presenza | Facoltativo |
Tipo | N/D |
<LocalTargetConnection>/<Path> elemento
Un percorso dell'endpoint scelto come target. L'endpoint deve fare riferimento a un proxy nello stesso organizzazione e ambiente come proxy che effettua la chiamata.
Usa questa opzione al posto di una coppia <APIProxy>/<ProxyEndpoint>
quando non
conoscere (o non poter fare affidamento) sul nome del proxy. Il percorso potrebbe essere un obiettivo affidabile.
<LocalTargetConnection> <Path>/data-manager</Path> </LocalTargetConnection>
Predefinito | N/D |
Presenza | Facoltativo |
Tipo | N/D |
Schemi
Variabili di flusso
Le variabili di flusso consentono il comportamento dinamico di criteri e flussi in fase di runtime, in base a HTTP intestazioni, contenuti dei messaggi o contesto di Flow. Sono disponibili le seguenti variabili di flusso predefinite dopo l'esecuzione del criterio ServiceCallout. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento per le variabili di flusso.
I callout di servizio hanno una propria richiesta e risposta e puoi accedere a questi dati tramite
come la codifica one-hot
delle variabili categoriche. Poiché il messaggio principale utilizza request.*
e
response.*
, utilizza i prefissi di variabile myrequest.*
e
calloutResponse.*
prefissi (i valori predefiniti nella configurazione ServiceCallout) di
ricevere i dati dei messaggi specifici di ServiceCallout. Il primo esempio nella tabella seguente mostra
come ottenere le intestazioni HTTP in ServiceCallout.
Variabile | Descrizione |
---|---|
Di seguito è riportato un esempio di come ottenere le intestazioni di richieste e risposte di ServiceCallout in modo simile alle intestazioni delle richieste e delle risposte principali.
dove calloutResponse è il nome della variabile per la Risposta nel Servizio Callout e myRequest è il nome della variabile per la richiesta. Ad esempio:
restituisce l'intestazione Content-Length della risposta ServiceCallout. |
Ambito: dal ServiceCallout in avanti Un'intestazione del messaggio nella richiesta o nella risposta ServiceCallout. Ad esempio, se l'API il target proxy è http://example.com e il target ServiceCallout è http://mocktarget.apigee.net, queste variabili sono le intestazioni del callout per http://mocktarget.apigee.net. |
servicecallout.requesturi |
Ambito: dall'inoltro della richiesta ServiceCallout L'URI TargetEndpoint per un criterio ServiceCallout. L'URI è l'URL dell'endpoint di destinazione senza il protocollo e le specifiche del dominio. |
servicecallout.{policy-name}.target.url |
Ambito: dall'inoltro della richiesta ServiceCallout L'URL di destinazione per un ServiceCallout. |
dove |
Ambito: dalla risposta ServiceCallout in avanti Il corpo della risposta dal ServiceCallout. |
servicecallout.{policy-name}.expectedcn |
Ambito: dall'inoltro della richiesta ServiceCallout Il nome comune previsto del TargetEndpoint come definito in un ServiceCallout . Ciò è significativo solo quando TargetEndpoint fa riferimento a un protocollo TLS/SSL endpoint. |
servicecallout.{policy-name}.failed |
Ambito: dalla risposta ServiceCallout in avanti Valore booleano che indica se il criterio ha avuto esito positivo, false o non riuscito, true. |
Errori
Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Apigee quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa | Correggi |
---|---|---|---|
steps.servicecallout.ExecutionFailed |
500 |
Questo errore può verificarsi quando:
|
build |
steps.servicecallout.RequestVariableNotMessageType |
500 |
La variabile Request specificata nel criterio non è di tipo Message . Ad esempio, se
si tratta di una stringa o di un altro tipo non legato ai messaggi, viene visualizzato questo errore. |
build |
steps.servicecallout.RequestVariableNotRequestMessageType |
500 |
La variabile Request specificata nel criterio non è di tipo RequestMessage . Per
Ad esempio, se si tratta di un tipo di risposta, visualizzerai questo errore. |
build |
googletoken.EmptyIDTokenAudience |
500 |
|
|
messaging.adaptors.http.filter.GoogleTokenGenerationFailure |
500 |
Questo errore può verificarsi se il proxy API è configurato con il ruolo <Authentication>
. Le possibili cause sono:
<GoogleAccessToken> è in uso e uno o più
vengono forniti ambiti non validi. Ad esempio, cerca errori di battitura o ambiti vuoti.
Solo per Apigee hybrid, controlla il log del container di runtime e cerca
|
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome errore | Causa | Correggi |
---|---|---|
URLMissing |
L'elemento <URL> all'interno di <HTTPTargetConnection>
mancante o vuoto. |
build |
ConnectionInfoMissing |
Questo errore si verifica se il criterio non ha un
<HTTPTargetConnection> o <LocalTargetConnection>
. |
build |
InvalidTimeoutValue |
Questo errore si verifica se il valore di <Timeout> è negativo o pari a zero. |
build |
FAILED_PRECONDITION |
Questo errore si verifica se l'account di servizio non è presente quando il proxy viene
configurate con il modulo <Authentication> del tag.
Ad esempio: Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service account identity, but one was not provided with the request. |
|
PERMISSION_DENIED |
Questo errore si verifica se si verifica un problema di autorizzazione con l'account di servizio
il proxy viene
configurate con il modulo <Authentication> del tag. Possibili cause:
|
Variabili di errore
Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come elencato nella precedente tabella Errori di runtime. Il nome dell'errore è l'ultima parte del codice di errore. | fault.name = "RequestVariableNotMessageType" |
servicecallout.policy_name.failed |
policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. | servicecallout.SC-GetUserData.failed = true |
Esempio di risposta di errore
{ "fault":{ "detail":{ "errorcode":"steps.servicecallout.RequestVariableNotMessageType" }, "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: request variable data_str value is not of type Message" } }
Esempio di regola di errore
<FaultRule name="RequestVariableNotMessageType"> <Step> <Name>AM-RequestVariableNotMessageType</Name> </Step> <Condition>(fault.name = "RequestVariableNotMessageType")</Condition> </FaultRule>
Argomenti correlati
- Generare o modificare i messaggi: criterioAssignMessage
- Estrai variabili: criterio ExtractVariables
- Variabili: Riferimento per le variabili di flusso
- Configurazione TLS/SSL
- Opzioni per la configurazione di TLS
- "Configurazione endpoint di destinazione TLS/SSL" in Informazioni di riferimento sulla configurazione del proxy API
- Proprietà di trasporto HTTP: riferimento sulle proprietà endpoint
- Alternativa a ServiceCallout: HTTPClient scritto in JavaScript; consulta Modello a oggetti JavaScript.