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 inserire 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 estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

  • In un caso d'uso esterno, esegui 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 della tua API, arricchendo e mashando 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 all'endpoint Target 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, questa opzione può essere utile se hai un proxy che offre alcune funzionalità di basso livello discrete che verranno utilizzate da uno o più altri 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 più altri proxy che mostrano i dati ai client.

Il criterio supporta le richieste tramite HTTP e HTTPS.

Samples

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) denominato data-manager, specificandone l'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 di 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.

Richiesta di geocodifica / definizione 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 della 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 messaggio di richiesta completo nella norma ServiceCallout che specifica un payload, un tipo di codifica come application/xml, intestazioni, parametri di modulo e così via.

Ecco un altro esempio in cui la richiesta viene formata prima di raggiungere le norme di 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 chiamata GeocodingRequest (che potrebbe essere compilata, ad esempio, da un criterio AssignMessage). Il messaggio di risposta viene assegnato alla variabile GeocodingResponse, dove è disponibile per l'analisi da parte di un criterio ExtractVariables o di codice personalizzato scritto in JavaScript o Java. Il criterio attende 30 secondi per la risposta dell'API Google Geocoding prima di scadere.

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 target e bilanciare il carico tra di essi. In questo esempio, il carico viene distribuito su due server target denominati httpbin e yahoo. Per informazioni sulla configurazione dei server di destinazione per il proxy e sul bilanciamento del carico, consulta Bilanciamento del carico tra i server di backend.

Informazioni sulle norme relative a 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 al fine di fornire dati sulla geolocalizzazione, recensioni dei clienti, articoli del catalogo di vendita al dettaglio di un partner e così via.

Un callout viene in genere utilizzato con altri due criteri: AssignMessage ed ExtractVariables.

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

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

    .

La composizione tipica del criterio ServiceCallout prevede:

  1. Criterio 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 un nome per l'oggetto di risposta restituito dal servizio di destinazione.

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

  3. Norma ExtractVariables: in genere definisce un'espressione JSONPath o XPath che analizza il messaggio generato dal 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 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 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 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 Ritirato

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.
Presenza 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 norma precedente nel flusso oppure puoi crearla in linea nella norma 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.

Il criterio restituisce un errore se il messaggio di richiesta non può essere risolto o se è di un tipo di messaggio di richiesta 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 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" variable="servicecallout.request"/>

Vediamo cosa significano questi valori predefiniti. Innanzitutto, clearPayload=true indica che viene creato un nuovo oggetto di richiesta ogni volta che viene eseguito il criterio ServiceCallout. Ciò significa che la richiesta e il percorso dell'URI della richiesta non vengono mai riutilizzati. In secondo luogo, il nome della variabile predefinito, 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, devi aggiungere 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 di richiesta.

 servicecallout.request Facoltativo
clearPayload

Se true, la variabile contenente il messaggio di richiesta viene cancellata dopo che la richiesta è stata inviata al target HTTP per liberare la memoria utilizzata dal messaggio di richiesta.

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

 true Facoltativo

Elemento <Request>/<IgnoreUnresolvedVariables>

Se impostato su true, il criterio ignora eventuali errori relativi alle variabili irrisolti 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 proxy API richiede la risposta della chiamata remota per un'ulteriore elaborazione.

Quando è presente, questo elemento specifica il nome della variabile che conterrà il messaggio di risposta ricevuto dal servizio esterno. La risposta del target viene assegnata alla variabile solo quando l'intera risposta viene letta correttamente dal criterio. 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 prosegue con i passaggi successivi del flusso. Inoltre, per ovvie ragioni, se non è presente un elemento Response, la risposta del target non è disponibile per l'elaborazione da parte dei passaggi successivi e non è possibile per il flusso proxy rilevare un errore nella chiamata remota. Un utilizzo comune per l'omissione dell'elemento Response quando si utilizza ServiceCallout: per 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 dal target. Non puoi impostare questo valore dinamicamente in fase di runtime. Se ServiceCallout raggiunge un timeout, viene restituito un codice 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 55000 millisecondi (55 secondi), l'impostazione del timeout HTTP predefinito per Apigee
Presenza Facoltativo
Tipo Numero intero

Elemento <HTTPTargetConnection>

Fornisce dettagli sul trasporto, ad esempio URL, TLS/SSL e proprietà HTTP. Consulta il <TargetEndpoint> riferimento alla configurazione.

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

La sintassi dell'elemento Authentication è la seguente:

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 accesso e lo inserisce nell'intestazione Authorization del messaggio inviato al sistema di destinazione. L'elemento HeaderName consente di specificare il nome di un'altra intestazione per contenere il token di accesso. 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

La sintassi dell'elemento HeaderName è la seguente:

Sintassi

<ServiceCallout>
...
  <Authentication>
    <HeaderName ref="FLOW_VARIABLE">STRING</HeaderName>
    <GoogleAccessToken>
      ...
    </GoogleAccessToken>
  </Authentication>
  ...
</ServiceCallout>

Con stringa statica

In questo esempio, il token bearer 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 a una variabile

In questo esempio, il token bearer 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, viene utilizzato questo valore anziché la 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>

La sintassi dell'elemento GoogleAccessToken è la seguente:

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 al gestore delle chiavi per recuperare un segreto 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 fare un callout a Cloud Run 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 ulteriori 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 dell'ambito

Specifica un ambito dell'API Google valido. Per ulteriori 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 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? È necessario che sia presente l'elemento secondario GoogleAccessToken o GoogleIDToken.
Tipo Stringa
Elemento principale <Authentication>
Elementi secondari <Audience>
<IncludeEmail>

La sintassi dell'elemento GoogleIDToken è la seguente:

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 del target (esclusi eventuali parametri di ricerca) viene utilizzato come segmento di 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à i claim email e email_verified dell'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 seguente, viene utilizzata una variabile per specificare il valore di un parametro della 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 per il servizio di backend. Per assistenza sulla configurazione di TLS/SSL, consulta Opzioni per la configurazione di TLS e "Configurazione di TargetEndpoint TLS/SSL" nel 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à del trasporto HTTP al servizio di backend. Per ulteriori informazioni, 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 e esegui il bilanciamento del carico su di essi. Consulta l'esempio Chiama i server di destinazione 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 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>

Oltre 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 il target 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 all'endpoint scelto come target. L'endpoint deve fare riferimento a un proxy nella stessa organizzazione e nello stesso ambiente del proxy che effettua la chiamata.

Utilizza questa opzione anziché una coppia <APIProxy>/<ProxyEndpoint> se 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 dei criteri e dei flussi in fase di esecuzione, in base agli 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 ulteriori informazioni sulle variabili di flusso, consulta Riferimento alle variabili di flusso.

I ServiceCallout hanno una propria richiesta e risposta 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 di ServiceCallout) per recuperare i dati del messaggio 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 come ottenere le intestazioni di richiesta e risposta di ServiceCallout in modo simile a come ottieni le intestazioni dalla richiesta e dalla risposta principali.

calloutResponse.header.HeaderName

myRequest.header.HeaderName

dove calloutResponse è il nome della variabile per la risposta nel callout del servizio e myRequest è il nome della variabile per la richiesta. Ad esempio:

calloutResponse.header.Content-Length

restituisce l'intestazione Content-Length della risposta ServiceCallout.

Ambito: da ServiceCallout in poi
Tipo: stringa
Autorizzazione: lettura/scrittura

Un'intestazione del messaggio nella richiesta o nella risposta di ServiceCallout. Ad esempio, se il target del proxy API è http://example.com e il target di ServiceCallout è http://mocktarget.apigee.net, queste variabili sono le intestazioni per il 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 di TargetEndpoint senza la specifica del protocollo e del dominio.
servicecallout.{policy-name}.target.url

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

L'URL di destinazione per un elemento ServiceCallout.

calloutResponse.content

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

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

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

Ambito: dalla risposta di ServiceCallout in poi
Tipo: booleano
Autorizzazione: Lettura/scrittura

Valore booleano che indica se il criterio è andato a buon fine (false) o se ha avuto esito negativo (true).

Errori

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Causa Correggi
steps.servicecallout.ExecutionFailed 500

Questo errore può verificarsi quando:

  • Al criterio viene chiesto di gestire input con formato non corretto o non validi.
  • Il servizio di destinazione di backend restituisce uno stato di errore (per impostazione predefinita, 4xx o 5xx).
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, viene visualizzato questo errore.
steps.servicecallout.RequestVariableNotRequestMessageType 500 La variabile Request specificata nel criterio non è di tipo RequestMessage. Ad esempio, se si tratta di un tipo Response, viene visualizzato questo errore.
googletoken.EmptyIDTokenAudience 500

<GoogleIDToken> è abilitato, ma useTargetUrl è impostato su false e non viene fornito alcun valore per <Audience> direttamente o tramite riferimento al momento dell'errore.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure 500 Questo errore può verificarsi se il proxy API è configurato con l'elemento <Authentication>. Tra le possibili cause rientrano:
  • L'account di servizio di cui è stato eseguito il deployment con il proxy:
    • non esiste nel tuo progetto
    • è stata disattivata
    • (Solo Apigee Hybrid) non ha concesso il ruolo roles/iam.serviceAccountTokenCreator all'account di servizio apigee-runtime.
  • L'API IAMCredentials è disattivata nel progetto di origine dell'account di servizio apigee-runtime.
  • Viene utilizzato l'elemento <GoogleAccessToken> e vengono forniti uno o più ambiti non validi. Ad esempio, cerca errori ortografici o ambiti vuoti.

    • Solo per Apigee Hybrid, controlla il log del contenitore di runtime e cerca GoogleTokenGenerationFailure per trovare messaggi di errore più dettagliati che potrebbero essere utili per il debug del problema.

    Errori di deployment

    Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

    Nome dell'errore Causa Correggi
    URLMissing L'elemento <URL> all'interno di <HTTPTargetConnection> è mancante o vuoto.
    ConnectionInfoMissing Questo errore si verifica se il criterio non contiene un elemento <HTTPTargetConnection> o <LocalTargetConnection>.
    InvalidTimeoutValue Questo errore si verifica se il valore <Timeout> è negativo o pari a zero.
    FAILED_PRECONDITION Questo errore si verifica se l'account di servizio non è presente quando il proxy è configurato con il tag <Authentication>.

    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 <Authentication>. Possibili cause:
    • L'account di servizio non esiste.
    • L'account di servizio non è stato creato nello stesso progetto Google Cloud dell'organizzazione Apigee.
    • Il programmatore dispone dell'autorizzazione iam.serviceAccounts.actAs per l'account di servizio. Per maggiori dettagli, vedi Informazioni sulle autorizzazioni degli account di servizio.

    Variabili di errore

    Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

    Variabili Dove Esempio
    fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'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