Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Cosa
Il criterio ServiceCallout consente di chiamare un altro servizio dal flusso proxy API. Puoi creare callout a un servizio esterno (ad esempio un endpoint di servizio RESTful esterno) o a servizi interni (ad esempio un proxy API nella stessa organizzazione e nello stesso ambiente).
Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.
- In un caso d'uso esterno, crei un callout a un'API di terze parti esterna al tuo proxy. La risposta dell'API di terze parti viene analizzata e inserita nel messaggio di risposta dell'API, arricchendo e componendo i dati per gli utenti finali dell'app. Puoi anche effettuare una richiesta utilizzando il criterio ServiceCallout nel flusso di richiesta, quindi 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 da cui si esegue la chiamata. Ad esempio, potrebbe essere utile quando hai un proxy che offre alcune funzionalità discrete di basso livello che verranno utilizzate da uno o più proxy. Ad esempio, un proxy che espone operazioni di creazione/lettura/aggiornamento/eliminazione con un datastore di backend potrebbe essere il proxy di destinazione per diversi altri proxy che espongono i dati ai client.
Il criterio supporta le richieste tramite HTTP e HTTPS.
Esempi
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 nello stesso ambiente) chiamato data-manager
, specificando il relativo endpoint proxy il cui nome è default
.
URL come variabile
<HTTPTargetConnection> <URL>http://example.com/{request.myResourcePath}</URL> </HTTPTargetConnection>
Questo esempio utilizza una variabile nell'URL per completare dinamicamente l'URL del target. La
parte relativa al protocollo dell'URL, http://
, non può essere specificata da una
variabile. Inoltre, devi utilizzare variabili separate per la parte del dominio dell'URL e per il resto dell'URL.
Geocodifica / definizione richiesta di Google
<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 di richiesta, puoi definirlo 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 intero messaggio di richiesta nel criterio ServiceCallout che specifica un payload, un tipo di codifica come application/xml
, intestazioni, parametri modulo e così via.
Ecco un altro esempio in cui la richiesta viene generata prima di raggiungere il criterio 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>
I contenuti del messaggio di richiesta vengono estratti da una variabile denominata GeocodingRequest
(che potrebbe essere completata, ad esempio, da un criterio di AttributionMessage). Il messaggio di risposta viene assegnato alla
variabile denominata GeocodingResponse
, dove può essere
analizzata da un criterio ExtractVariables o mediante un codice personalizzato scritto in JavaScript
o Java. Il criterio attende 30 secondi la risposta dall'API Google Geocoding prima del timeout.
Chiama i server di destinazione
<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 essi. In questo esempio, il carico viene distribuito tra due server di destinazione denominati httpbin
e yahoo
. Per informazioni sulla configurazione dei server di destinazione per il proxy e sulla configurazione del bilanciamento del carico, consulta Bilanciamento del carico tra server di backend.
Informazioni sulle norme di ServiceCallout
Esistono molti scenari in cui puoi utilizzare un criterio ServiceCallout nel proxy API. Ad esempio, puoi configurare un proxy API per effettuare chiamate a un servizio esterno in modo da fornire dati di geolocalizzazione, recensioni dei clienti, articoli da un catalogo al dettaglio di un partner e così via.
Un callout viene generalmente utilizzato con altri due criteri: AttributionMessage ed ExtractVariables.
- Request: AttributionMessage compila il messaggio di richiesta inviato al servizio remoto.
-
Response: ExtractVariables analizza la risposta ed estrae contenuti specifici.
La tipica composizione delle norme di ServiceCallout prevede:
- CriterioAssignMessage: crea un messaggio di richiesta, compila le intestazioni HTTP e parametri di ricerca, imposta il verbo HTTP e così via.
-
Criterio di callout del servizio: fa riferimento a un messaggio creato dal criterio AssignMessage, definisce un URL di destinazione per la chiamata esterna e definisce un nome per l'oggetto risposta che il servizio di destinazione restituisce.
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 in seguito recuperarli dalla cache?
- Criterio ExtractVariables: in genere definisce un'espressione JSONPath o XPath che analizza il messaggio generato da ServiceCallout. Il criterio imposta quindi le variabili contenenti i valori analizzati dalla risposta ServiceCallout.
Gestione personalizzata degli errori
Riferimento elemento
Di seguito sono riportati gli elementi e gli attributi che puoi configurare per 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>
Attributi <ServiceCallout>
<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 |
Elemento <Request>
Specifica la variabile contenente il messaggio di richiesta che viene inviato dal proxy API all'altro servizio. La variabile può essere creata da un criterio precedente nel flusso oppure 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 utilizzata per il criterioAssignMessage.
Il criterio restituisce un errore se il messaggio di richiesta non può essere risolto o se è di tipo non valido.
Nell'esempio più semplice, passi una variabile contenente il messaggio di richiesta completato in precedenza nel flusso del proxy API:
<Request clearPayload="true" variable="myRequest"/>
In alternativa, puoi completare 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 dei suoi attributi, Apigee assegna i seguenti valori predefiniti:
<Request clearPayload="true" variables="servicecallout.request"/> Vediamo il significato di questi valori predefiniti. Innanzitutto,
È importante conoscere questo nome predefinito se utilizzi il 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 l'opzione clearPayload su false solo se il messaggio di richiesta è obbligatorio dopo l'esecuzione del callout di servizio. |
true | Facoltativo |
Elemento <Request>/< monitorUnresolvedVariables>
Se impostato su true, il criterio ignora qualsiasi errore di variabile non risolto nella richiesta.
<Request clearPayload="true" variable="myRequest"> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </Request>
Predefinito | false |
Presenza | Facoltativo |
Tipo | Booleano |
Elemento <Response>
Includi questo elemento quando la logica del proxy API richiede la risposta dalla chiamata remota per un'ulteriore elaborazione.
Se questo elemento è presente, specifica il nome della variabile che conterrà il messaggio di risposta ricevuto dal servizio esterno. La risposta dalla destinazione viene assegnata alla variabile solo quando l'intera risposta viene letta dal criterio. Se per qualsiasi motivo la chiamata remota non va a buon fine, il criterio restituisce un errore.
Se questo elemento viene omesso, il proxy API non attende una risposta; l'esecuzione del flusso del proxy API continua con tutti i passaggi del flusso successivi. Inoltre, per indicare l'ovvio, senza
elemento Response
, la risposta della destinazione non è disponibile per l'elaborazione nei
passaggi successivi e il flusso proxy non può rilevare un errore nella chiamata remota.
Utilizzo comune per omettere l'elemento Response
quando si utilizza ServiceCallout: per registrare i messaggi su un sistema esterno.
<Response>calloutResponse</Response>
Predefinito | NA |
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <Timeout>.
Il tempo in millisecondi durante il quale il criterio ServiceCallout attende 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 errore HTTP 500, il criterio non viene applicato e il proxy API entra in uno stato di errore, come descritto in Gestione degli errori.
<Timeout>30000</Timeout>
Predefinito | 55000 millisecondi (55 secondi), l'impostazione di timeout HTTP predefinita per Apigee |
Presenza | Facoltativo |
Tipo | Numero intero |
Elemento <HTTPTargetConnection>
Fornisce dettagli sul trasporto come URL, TLS/SSL e proprietà HTTP. Consulta il riferimento alla configurazione di <TargetEndpoint>
.
<HTTPTargetConnection> <URL>http://example.com</URL> <LoadBalancer/> <SSLInfo/> <Properties/> </HTTPTargetConnection>
Predefinito | N/D |
Presenza | Obbligatorio |
Tipo | N/D |
Elemento <HTTPTargetConnection>/<Authentication>
Genera token Google OAuth 2.0 o OpenID Connect emessi 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 Utilizzare l'autenticazione Google. Con la corretta configurazione, il criterio crea un token di autenticazione per te e lo aggiunge alla richiesta di servizio.
Gli elementi secondari, GoogleAccessToken
e GoogleIDToken
, consentono di configurare il criterio per generare token Google OAuth o OpenID Connect. Devi scegliere uno di questi elementi secondari a seconda del tipo di servizio che vuoi chiamare.
Il criterio ServiceCallout supporta solo le chiamate ai 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
L'esempio seguente mostra l'elemento GoogleAccessToken
:
<Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication>
Utilizzo di GoogleIDToken
L'esempio seguente mostra l'elemento GoogleIDToken
:
<Authentication> <GoogleIDToken> <Audience>https://httpserver0-bar.run.app</Audience> <IncludeEmail>false</IncludeEmail> </GoogleIDToken> </Authentication>
Utilizzo di HeaderName
L'esempio seguente mostra 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 LifetimeInSecond
L'esempio seguente mostra 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 token di connessione e lo inserisce nell'intestazione Authorization
del messaggio inviato al sistema di destinazione.
L'elemento HeaderName
consente di specificare il nome di un'intestazione diversa
per contenere il token di connessione. Questa funzionalità è particolarmente utile quando la destinazione è un servizio Cloud Run che utilizza l'intestazione X-Serverless-Authorization
. L'intestazione Authorization
, se presente, non viene modificata e viene anch'essa inviata nella richiesta.
Predefinito | N/D |
Obbligatorio? | No |
Tipo | Stringa |
Elemento principale | <Authentication> |
Elementi secondari | Nessun valore |
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 inviata al sistema di destinazione. L'intestazione Authorization
, se presente, non viene modificata e viene anch'essa inviata nella richiesta.
<Authentication> <HeaderName>X-Serverless-Authorization</HeaderName> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-platform</Scope> </Scopes> </GoogleAccessToken> </Authentication>
Con riferimento alla variabile
In questo esempio, il token di connessione generato viene aggiunto, per impostazione predefinita, a un'intestazione denominata X-Serverless-Authorization
che viene inviata al sistema di destinazione. Se my-variable
ha un valore, questo viene utilizzato
al posto della stringa predefinita. L'intestazione Authorization
, se presente, non viene modificata e viene anch'essa inviata 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, ad esempio Cloud Logging e Secret Manager.
Predefinito | N/D |
Obbligatorio? | Deve essere presente l'elemento secondario GoogleAccessToken o GoogleIDToken . |
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
L'esempio seguente mostra 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 creare un callout in Cloud eseguito 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 Ambiti
Identifica gli ambiti da includere nel token di accesso OAuth 2.0. Per maggiori informazioni, consulta
Ambiti OAuth 2.0 per le API di Google. Puoi aggiungere uno o più elementi secondari <Scope>
sotto 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 maggiori informazioni, consulta 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 LifetimeInSecond
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
L'esempio seguente mostra 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 a cui il token concede l'accesso.
Se il valore di Audience
è vuoto o la variabile ref
non restituisce un valore valido e
useTargetUrl
è true
, come segmento di pubblico viene utilizzato l'URL del target (esclusi eventuali
parametri di ricerca). Per impostazione predefinita, 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à le attestazioni dell'account di servizio email
e email_verified
.
Predefinito | false |
Obbligatorio? | Facoltativo |
Tipo | Booleano |
Elemento principale | <GoogleIDToken> |
Elementi secondari | Nessuno. |
Elemento <HTTPTargetConnection>/<URL>
L'URL del servizio chiamato:
<HTTPTargetConnection> <URL>http://example.com</URL> </HTTPTargetConnection>
Puoi fornire dinamicamente una parte dell'URL con una variabile. Tuttavia, la parte relativa al protocollo dell'URL, http:// di seguito, non può essere specificata da una variabile. Nell'esempio successivo, utilizzi una variabile per specificare il valore di un parametro di 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, utilizza una 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 |
Elemento <HTTPTargetConnection>/<SSLInfo>
La configurazione TLS/SSL al servizio di backend. Per assistenza sulla configurazione TLS/SSL, consulta Opzioni per la configurazione di TLS e "Configurazione TLS/SSL TargetEndpoint" al riferimento sulla 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 |
Elemento <HTTPTargetConnection>/<Properties>
Proprietà di trasporto HTTP al servizio di backend. Per maggiori informazioni, consulta Riferimento alle 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 |
Elemento <HTTPTargetConnection>/<LoadBalancer>
Chiama uno o più server di destinazione ed esegui il bilanciamento del carico su questi server. Consulta l'esempio Server di destinazione delle chiamate nella sezione Esempi. Vedi anche Bilanciamento del carico tra server di backend. Vedi anche Callout endpoint/server di destinazione in cui vengono illustrati i modi per chiamare i server di destinazione sia dal criterio ServiceCallout sia dall'utilizzo delle 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 |
Elemento <LocalTargetConnection>
Specifica un proxy locale, ovvero un proxy nella stessa organizzazione e nello stesso ambiente, come 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 |
Elemento <LocalTargetConnection>/<APIProxy>
Il nome di un proxy API che è la destinazione di una chiamata locale. Il proxy deve trovarsi nella stessa organizzazione e nello stesso ambiente del proxy che effettua la chiamata.
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
Insieme all'elemento <APIProxy>
, includi l'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 |
Elemento <LocalTargetConnection>/<ProxyEndpoint>
Il nome dell'endpoint proxy che deve essere la destinazione delle chiamate. Questo è un endpoint proxy nel proxy API specificato con l'elemento <APIProxy>
.
<LocalTargetConnection> <APIProxy>data-manager</APIProxy> <ProxyEndpoint>default</ProxyEndpoint> </LocalTargetConnection>
Predefinito | N/D |
Presenza | Facoltativo |
Tipo | N/D |
Elemento <LocalTargetConnection>/<Path>
Un percorso dell'endpoint target. L'endpoint deve fare riferimento a un proxy nella stessa organizzazione e nello stesso ambiente del proxy che effettua la chiamata.
Utilizza questo valore anziché una coppia <APIProxy>/<ProxyEndpoint>
quando non conosci o non puoi fare affidamento sul nome del proxy. Il percorso potrebbe essere un target affidabile.
<LocalTargetConnection> <Path>/data-manager</Path> </LocalTargetConnection>
Predefinito | N/D |
Presenza | Facoltativo |
Tipo | N/D |
Schema
Variabili di flusso
Le variabili di flusso consentono il comportamento dinamico dei criteri e dei flussi in fase di runtime, in base alle intestazioni HTTP, ai contenuti dei messaggi o al contesto del flusso. Le seguenti variabili di flusso predefinite sono disponibili dopo l'esecuzione di un criterio ServiceCallout. Per maggiori informazioni sulle variabili di flusso, consulta Riferimento per le variabili di flusso.
I callout di servizio hanno le proprie richieste e risposte e puoi accedere a questi dati tramite le variabili. Poiché il messaggio principale utilizza i prefissi delle variabili request.*
e response.*
, utilizza i prefissi myrequest.*
e calloutResponse.*
(i valori predefiniti nella configurazione ServiceCallout) per ottenere i dati dei messaggi specifici per ServiceCallout. Il primo esempio nella tabella seguente mostra come ricevere le intestazioni HTTP in ServiceCallout.
Variabile | Descrizione |
---|---|
Di seguito è riportato un esempio di come ottenere le intestazioni delle richieste e delle risposte ServiceCallout simili a come otterresti le intestazioni dalla richiesta e dalla risposta principali.
dove calloutResponse è il nome della variabile per la risposta nel callout di servizio e myRequest è il nome della variabile della richiesta. Ad esempio:
restituisce l'intestazione Content-Length della risposta ServiceCallout. |
Ambito: dal callout Service Un'intestazione di messaggio nella richiesta o nella risposta ServiceCallout. Ad esempio, se la destinazione del proxy API è http://example.com e la destinazione ServiceCallout è http://mocktarget.apigee.net, queste variabili sono le intestazioni del callout diretto a http://mocktarget.apigee.net. |
servicecallout.requesturi |
Ambito: dall'inoltro della richiesta ServiceCallout L'URI TargetEndpoint per un criterio ServiceCallout. L'URI è l'URL TargetEndpoint senza il protocollo e la specifica di dominio. |
servicecallout.{policy-name}.target.url |
Ambito: dall'inoltro della richiesta ServiceCallout L'URL di destinazione per un callout di servizio. |
dove |
Ambito: dall'inoltro della risposta ServiceCallout Il corpo della risposta da ServiceCallout. |
servicecallout.{policy-name}.expectedcn |
Ambito: dall'inoltro della richiesta ServiceCallout Il nome comune previsto di TargetEndpoint come indicato in un criterio ServiceCallout. Questo è significativo solo quando TargetEndpoint fa riferimento a un endpoint TLS/SSL. |
servicecallout.{policy-name}.failed |
Ambito: dall'avanzamento della risposta ServiceCallout Valore booleano che indica se il criterio ha avuto esito positivo, falso o non riuscito, vero. |
Errori
Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
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 si può verificare 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 di messaggio, visualizzerai questo errore. |
build |
steps.servicecallout.RequestVariableNotRequestMessageType |
500 |
La variabile Request specificata nel criterio non è di tipo RequestMessage . 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 l'elemento <Autenticazione>. Le possibili cause includono:
<GoogleAccessToken> e vengono forniti uno o più
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 elemento <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 è configurato con il tag <Autenticazione>.
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 se il proxy è configurato con il tag <Autenticazione>. Possibili cause:
|
Variabili di errore
Queste variabili vengono impostate quando si verifica un errore di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è 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="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType"> <Step> <Name>AM-RequestVariableNotMessageType</Name> </Step> <Condition>(fault.name = "RequestVariableNotMessageType")</Condition> </FaultRule>
Argomenti correlati
- Generare o modificare i messaggi: criterioAssignMessage
- Estrai le variabili: norma ExtractVariables
- Variabili: Riferimento per le variabili di flusso
- Configurazione TLS/SSL
- Opzioni per la configurazione di TLS
- "Configurazione TLS/SSL TargetEndpoint" nella Guida di riferimento alla configurazione del proxy API
- Proprietà di trasporto HTTP: riferimento sulle proprietà degli endpoint
- Alternativa a ServiceCallout: HTTPClient scritto in JavaScript, consulta la sezione Modello a oggetti JavaScript.