Norme relative a ServiceCallout

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Il criterio ServiceCallout ti consente di chiamare un altro servizio dal flusso del proxy API. Puoi effettuare chiamate 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).

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di 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, effettui 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 combinando i dati per gli utenti finali dell'app. Puoi anche effettuare una richiesta utilizzando il criterio ServiceCallout nel flusso della richiesta, quindi passare le informazioni nella risposta a TargetEndpoint del proxy API.
  • In un altro caso d'uso, chiami un proxy che si trova nella stessa organizzazione e nello stesso ambiente di quello da cui stai chiamando. Ad esempio, potresti trovare questa funzionalità utile quando hai un proxy che offre alcune funzionalità discrete di basso livello che uno o più altri proxy utilizzeranno. Ad esempio, un proxy che espone 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 tramite HTTP e HTTPS.

Campioni

Chiamata locale a un proxy interno

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

Questo esempio crea un callout a un proxy API locale (ovvero 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 compilare dinamicamente l'URL del target. La parte del protocollo dell'URL, http://, non può essere specificata da una variabile. Inoltre, devi utilizzare variabili separate per la parte di dominio dell'URL e per il resto dell'URL.

Geocodifica Google / richiesta di definizione

<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 una policy come AssignMessage per creare l'oggetto richiesta, puoi definirlo direttamente nella policy ServiceCallout. In questo esempio, il criterio ServiceCallout imposta i valori di treparametri di ricercay passati al servizio esterno. Puoi creare un intero messaggio di richiesta nella norma ServiceCallout che specifica un payload, un tipo di codifica come application/xml, intestazioni, parametri del modulo e così via.

Ecco un altro esempio in cui la richiesta viene formata 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>

Il contenuto del messaggio di richiesta viene estratto da una variabile chiamata GeocodingRequest (che potrebbe essere compilata, ad esempio, da un criterio AssignMessage). Il messaggio di risposta viene assegnato alla variabile denominata GeocodingResponse, dove è disponibile per l'analisi da parte di un ExtractVariables policy o da codice personalizzato scritto in JavaScript o Java. Prima del timeout, il criterio attende 30 secondi la risposta dell'API Google Geocoding.

Server di destinazione delle chiamate

<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>

Questa policy utilizza l'attributo LoadBalancer per chiamare i server di destinazione ed eseguire il bilanciamento del carico tra questi. In questo esempio, il carico viene distribuito su due server di destinazione denominati httpbin e yahoo. Per informazioni sulla configurazione dei server di destinazione per il proxy e sul bilanciamento del carico, vedi Bilanciamento del carico tra server di backend.

Informazioni sulla norma 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 per fornire dati di geolocalizzazione, recensioni dei clienti, articoli del catalogo retail di un partner e così via.

Un callout viene in genere utilizzato con altre due norme: AssignMessage ed ExtractVariables.

  • Request: AssignMessage compila il messaggio di richiesta inviato al servizio remoto.

  • Response: ExtractVariables analizza la risposta ed estrae contenuti specifici.

La composizione tipica dei criteri ServiceCallout prevede:

  1. Norma AssignMessage: crea un messaggio di richiesta, compila le intestazioni HTTP, parametri di ricerca, imposta il verbo HTTP e così via.

  2. Criterio ServiceCallout: 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 restituito dal servizio di destinazione.

    Per migliorare le prestazioni, puoi anche memorizzare nella cache le risposte ServiceCallout, come descritto in Come posso memorizzare nella cache i risultati del criterio ServiceCallout e recuperarli in un secondo momento?

  3. Norme ExtractVariables: in genere definiscono 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 degli errori personalizzata

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare in queste norme:

<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 Presence
name

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError

Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:

 falso Facoltativo
enabled

Imposta su true per applicare il criterio.

Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Deprecato

Elemento <DisplayName>

Da utilizzare insieme 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/D

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presence Facoltativo
Tipo Stringa

Elemento <Request>

Specifica la variabile contenente il messaggio di richiesta inviato dal proxy API all'altro servizio. La variabile può essere creata da una policy precedente nel flusso oppure puoi crearla inline nella policy 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 del criterio AssignMessage.

La norma restituisce un errore se il messaggio di richiesta non può essere risolto o è di un tipo non valido.

Nell'esempio più semplice, passi una variabile contenente il messaggio di richiesta 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 nella stessa norma ServiceCallout:

<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"/>

Vediamo cosa significano questi valori predefiniti. Innanzitutto, clearPayload=true significa che viene creato un nuovo oggetto richiesta ogni volta che viene eseguita la policy ServiceCallout. Ciò significa che la richiesta e il percorso URI della richiesta non vengono mai riutilizzati. In secondo luogo, il nome della variabile predefinita, servicecallout.request, è un nome riservato che viene assegnato alla richiesta se non fornisci un nome.

È importante conoscere questo nome predefinito se utilizzi la mascheratura dei dati: se ometti il nome della variabile, devi aggiungere servicecallout.request alla configurazione della maschera. Ad esempio, se vuoi mascherare l'intestazione Authorization in modo che non venga visualizzata nelle sessioni di debug, aggiungi quanto segue alla configurazione di mascheramento per acquisire il nome predefinito:

servicecallout.request.header.Authorization.
Presenza Facoltativo.
Tipo N/D

Attributi

Attributo Descrizione Predefinito Presenza
variabile

Nome della variabile che conterrà il messaggio della richiesta.

 servicecallout.request Facoltativo
clearPayload

Se true, la variabile contenente il messaggio di richiesta viene cancellata dopo l'invio della richiesta alla destinazione HTTP per liberare la memoria utilizzata dal messaggio di richiesta.

Imposta l'opzione clearPayload su false solo se il messaggio di richiesta è necessario dopo l'esecuzione di ServiceCallout.

 true Facoltativo

Elemento <Request>/<IgnoreUnresolvedVariables>

Se impostata su true, la policy ignora qualsiasi errore di variabile non risolto nella richiesta.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>
Predefinito falso
Presenza Facoltativo
Tipo Booleano

Elemento <Response>

Includi questo elemento quando la logica del proxy API richiede la risposta della chiamata remota per un'ulteriore elaborazione.

Quando 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 correttamente dalla policy. Se la chiamata remota non va a buon fine per qualsiasi motivo, 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 i passaggi del flusso successivi. Inoltre, per ovvie ragioni, senza l'elemento Response, la risposta della destinazione non è disponibile per l'elaborazione da parte dei passaggi successivi e non è possibile rilevare un errore nella chiamata remota. Un utilizzo comune dell'omissione dell'elemento Response quando si utilizza ServiceCallout: registrare i messaggi in un sistema esterno.

 <Response>calloutResponse</Response>
Predefinito NA
Presenza Facoltativo
Tipo Stringa

Elemento <Timeout>

Il tempo in millisecondi durante il quale il criterio ServiceCallout attenderà una risposta dalla destinazione. Non puoi impostare questo valore in modo dinamico in fase di runtime. Se ServiceCallout raggiunge il timeout, viene restituito un errore HTTP 500, il criterio non va a buon fine e il proxy API entra in uno stato di errore, come descritto in Gestione degli errori.

<Timeout>30000</Timeout>
Predefinito 55.000 millisecondi (55 secondi), l'impostazione di timeout HTTP predefinita per Apigee
Presenza Facoltativo
Tipo Numero intero

Elemento <HTTPTargetConnection>

Fornisce i dettagli di 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 a servizi Google e 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 la configurazione corretta, il criterio crea un token di autenticazione e lo aggiunge alla richiesta di servizio.

Gli elementi secondari, GoogleAccessToken e GoogleIDToken, ti 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 LifetimeInSeconds

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 ti consente di specificare il nome di un'intestazione diversa per contenere il token di autenticazione. Questa funzionalità è particolarmente utile quando la destinazione è un servizio Cloud Run che utilizza l'intestazione X-Serverless-Authorization. L'intestazione Authorization, se presente, viene lasciata invariata e inviata anche 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 autenticazione 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, viene lasciata invariata e inviata anche 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 autenticazione 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, viene lasciata invariata e inviata anche 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? 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 effettuare un callout a Cloud Run dalla policy 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> sotto questo elemento.

Predefinito N/D
Obbligatorio? Obbligatorio
Tipo Stringa
Elemento principale <GoogleAccessToken>
Elementi secondari <Scope>

Elemento secondario dell'ambito

Specifica un ambito API Google valido. 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 del token di accesso in secondi.

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 Audience

Il pubblico per il 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, l'URL della destinazione (esclusi i parametri di query) viene utilizzato come pubblico. 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 email e email_verified del account di servizio.

Predefinito falso
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 parte dell'URL in modo dinamico con una variabile. Tuttavia, la parte del 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 del servizio di backend. Per assistenza sulla configurazione di TLS/SSL, vedi Opzioni per la configurazione di TLS e "Configurazione TargetEndpoint 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

Elemento <HTTPTargetConnection>/<Properties>

Proprietà di trasporto HTTP al servizio di backend. Per saperne di più, consulta 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

Elemento <HTTPTargetConnection>/<LoadBalancer>

Chiama uno o più server di destinazione ed esegui il bilanciamento del carico. Consulta l'esempio Server di destinazione delle chiamate nella sezione Esempi. Vedi anche Bilanciamento del carico tra server di backend. Consulta anche Callout endpoint/server di destinazione, che illustra i modi per chiamare i server di destinazione sia dal criterio ServiceCallout sia utilizzando le regole di routing.

<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 destinazione dei callout di servizio.

Per specificare ulteriormente la destinazione, 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>

Oltre all'elemento <APIProxy>, includi l'elemento <ProxyEndpoint> per specificare il nome dell'endpoint proxy a cui deve essere indirizzata 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. Si tratta di 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 verso l'endpoint di destinazione. 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 una destinazione 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 alle intestazioni HTTP, al contenuto dei messaggi o al contesto del flusso. Le seguenti variabili di flusso predefinite sono disponibili dopo l'esecuzione di un criterio ServiceCallout. Per ulteriori informazioni sulle variabili di flusso, consulta il riferimento alle variabili di flusso.

ServiceCallouts ha una propria richiesta e risposta e puoi accedere a questi dati tramite 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 dati dei messaggi specifici per ServiceCallout. Il primo esempio nella tabella seguente mostra come ottenere le intestazioni HTTP in ServiceCallout.

Variabile Descrizione

Di seguito è riportato un esempio di recupero delle intestazioni di richiesta e risposta ServiceCallout in modo simile a come si ottengono le intestazioni dalla richiesta e dalla risposta principali.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

dove calloutResponse è il nome della variabile per la risposta nel Service Callout e myRequest è il nome della variabile per la richiesta. Ad esempio:

calloutResponse.header.Content-Length

restituisce l'intestazione Content-Length della risposta ServiceCallout.

Scope: da ServiceCallout in poi
Type: String
Permission: Read/Write

Un'intestazione del messaggio nella richiesta o nella risposta ServiceCallout. Ad esempio, se la destinazione del proxy API è http://example.com e la destinazione di ServiceCallout è http://mocktarget.apigee.net, queste variabili sono le intestazioni del callout a http://mocktarget.apigee.net.
servicecallout.requesturi

Ambito: dalla richiesta ServiceCallout in poi
Tipo: stringa
Autorizzazione: lettura/scrittura

L'URI TargetEndpoint per un criterio ServiceCallout. L'URI è l'URL TargetEndpoint senza la specifica di protocollo e dominio.
servicecallout.{policy-name}.target.url

Ambito: dalla richiesta ServiceCallout in poi
Tipo: stringa
Autorizzazione: lettura/scrittura

L'URL di destinazione di un callout di servizio.

calloutResponse.content

dove calloutResponse è il <Response>nome della variabile nella configurazione ServiceCallout.

Scope: dalla risposta ServiceCallout in poi
Type: String
Permission: Read/Write

Il corpo della risposta di ServiceCallout.
servicecallout.{policy-name}.expectedcn

Ambito: dalla richiesta ServiceCallout in poi
Tipo: stringa
Autorizzazione: lettura/scrittura

Il nome comune previsto di TargetEndpoint a cui si fa riferimento in un criterio ServiceCallout. Questo valore è significativo solo quando TargetEndpoint fa riferimento a un endpoint TLS/SSL.
servicecallout.{policy-name}.failed

Scope: dalla risposta ServiceCallout in poi
Type: booleano
Permission: lettura/scrittura

Valore booleano che indica se il criterio è stato applicato (false) o meno (true).

Errori

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.servicecallout.ExecutionFailed 500

This error can occur when:

  • The policy is asked to handle input that is malformed or otherwise invalid.
  • The backend target service returns an error status (by default, 4xx or 5xx).
steps.servicecallout.RequestVariableNotMessageType 500 The Request variable specified in the policy is not of type Message. For example, if it's a string or other non-message type, you'll see this error.
steps.servicecallout.RequestVariableNotRequestMessageType 500 The Request variable specified in the policy is not of type RequestMessage. For example, if it's a Response type, you'll see this error.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> is enabled but useTargetUrl is set to false and no value is provided to <Audience> either directly or through reference at the time of error.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 This error can happen if the API proxy is configured with the <Authentication> element. Possible causes include:
  • The service account deployed with the proxy:
    • does not exist in your project
    • has been disabled
    • (Apigee hybrid only) has not granted the roles/iam.serviceAccountTokenCreator role on the apigee-runtime service account.
  • The IAMCredentials API is disabled in the source project of the apigee-runtime service account.
  • The <GoogleAccessToken> element is used and one or more invalid scopes are provided. For example, look for typos or empty scopes.

    • For Apigee hybrid only, check the runtime container's log and search for GoogleTokenGenerationFailure to find more detailed error messages that may help with debugging the problem.

    Deployment errors

    These errors can occur when you deploy a proxy containing this policy.

    Error name Cause Fix
    URLMissing The <URL> element inside <HTTPTargetConnection> is missing or empty.
    ConnectionInfoMissing This error happens if the policy does not have an <HTTPTargetConnection> or <LocalTargetConnection> element.
    InvalidTimeoutValue This error happens if the <Timeout> value is negative or zero.
    FAILED_PRECONDITION This error happens if the service account is missing when the proxy is configured with the <Authentication> tag.

    For example: 

    Deployment of \"organizations/foo/apis/apiproxy/revisions/1\" requires a service
          account identity, but one was not provided with the request.
    PERMISSION_DENIED This error happens if there is a permission problem with the service account if the proxy is configured with the <Authentication> tag. Possible causes:
    • The service account does not exist.
    • The service account was not created in the same Google Cloud project as the Apigee organization.
    • The deployer does have iam.serviceAccounts.actAs permission on the service account. For details, see About service account permissions.

    Fault variables

    These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

    Variables Where Example
    fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "RequestVariableNotMessageType"
    servicecallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. servicecallout.SC-GetUserData.failed = true

    Example error response

    {
   "fault":{
      "detail":{
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]:
            request variable data_str value is not of type Message"
   }
}

    Example fault rule

    <FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

    Argomenti correlati