Norme relative a ServiceCallout

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Cosa

Questo criterio consente di chiamare un altro servizio dal flusso proxy API. Tu possono effettuare callout a un servizio esterno (ad esempio a un endpoint di servizio RESTful esterno) interni (ad esempio, un proxy API nella stessa organizzazione e nello stesso ambiente).

• In un caso d'uso esterno, crei un callout per un'API di terze parti esterna al tuo proxy. La risposta dell'API di terze parti viene analizzata e inserita nella risposta dell'API arricchendo e integrando i contenuti i dati per gli utenti finali dell'app. Puoi anche inviare una richiesta utilizzando il criterio callout di servizio nel flusso della richiesta, poi passa le informazioni nella risposta al TargetEndpoint del proxy API.
• In un altro caso d'uso, chiami un proxy che si trova nella stessa organizzazione e nello stesso ambiente di da quello da cui stai chiamando. Ad esempio, potrebbe essere utile se hai un proxy che offre alcune discrete funzionalità di basso livello che verranno utilizzate da uno o più altri proxy. Per Ad esempio, un proxy che espone le operazioni di creazione/lettura/aggiornamento/eliminazione con un datastore di backend potrebbe essere il proxy di destinazione per più proxy che espongono i dati ai client.

Il criterio supporta le richieste su HTTP e HTTPS.

Campioni

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

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

<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>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

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

Informazioni sulle norme relative ai callout di servizio

Esistono molti scenari in cui è possibile utilizzare un criterio callout di servizio nel proxy API. Per Ad esempio, puoi configurare un proxy API per effettuare chiamate a un servizio esterno dati di geolocalizzazione, recensioni dei clienti, articoli del catalogo di un partner e così via.

In genere, un callout viene utilizzato con due altri criteri: Assegna messaggio ed Estrai variabili.

• Richiesta: Assegna messaggio compila il messaggio di richiesta inviato al telecomando completamente gestito di Google Cloud.

• Risposta: l'opzione Estrai variabili analizza la risposta ed estrae specifiche. contenuti.

La tipica composizione delle norme relative ai callout di servizio prevede:

1. Assegna messaggio policy: crea un messaggio di richiesta, compila le intestazioni HTTP e i parametri di query, imposta il parametro HTTP verbo e così via.
2. Criterio Callout di servizio: fa riferimento a un messaggio creato dall'Assegna messaggio policy, definisce un URL di destinazione per la chiamata esterna e definisce un nome per l'oggetto di risposta restituito dal servizio di destinazione.
   
   Per migliorare le prestazioni, puoi anche memorizzare nella cache le risposte ai callout di servizio, come descritto in Thread della community Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html.
3. Estrai variabili policy: in genere definisce un'espressione JSONPath o XPath che analizza il messaggio generato dal callout di servizio. Il criterio quindi imposta variabili contenenti i valori analizzati dalla Risposta al callout del servizio.

Consulta la sezione Utilizzo dei criteri composizione per un proxy API di esempio completo che utilizza il criterio callout di servizio insieme a i criteri Assegna messaggio ed Estrai variabili.

Gestione personalizzata degli errori

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare su questo criterio:

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

<ServiceCallout> attributi

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

&lt;Request&gt; elemento

Specifica la variabile contenente il messaggio di richiesta che viene inviato dal proxy API allo altro servizio. La variabile può essere creata da un criterio precedente nel flusso oppure puoi crearla in linea nelle norme sui callout di servizio.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

La sintassi dei tag <Remove>, <Copy>, <Add> e <Set> è la stessa della Assegna messaggio .

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

Nell'esempio più semplice, passi una variabile contenente il messaggio di richiesta che è stato compilato in precedenza nel flusso del proxy API:

<Request clearPayload="true" variable="myRequest"/>

In alternativa, puoi compilare il messaggio di richiesta inviato al servizio esterno utilizzando il criterio relativo ai callout del servizio 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>

Attributi

&lt;Request&gt;/&lt;IgnoreUnresolvedVariables&gt; elemento

Se impostato su true, il criterio ignora eventuali errori relativi alle variabili non risolte presenti nella richiesta.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request> 

&lt;Response&gt; elemento

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

Quando è presente, questo elemento specifica il nome della variabile che conterrà il messaggio di risposta ricevuto dal servizio esterno. La risposta dal target è assegnata a la variabile solo quando l'intera risposta viene letta correttamente dal criterio. Se la chiamata remota non riesce per qualsiasi motivo, il criterio restituisce un errore.

Se questo elemento viene omesso, il proxy API non attende una risposta; Flusso proxy API l'esecuzione continua con i passaggi successivi del flusso. Inoltre, per indicare l'ovvio, senza Response, la risposta dal target non è disponibile per l'elaborazione in base a passaggi successivi e il flusso proxy non rileva in alcun modo un errore nella chiamata remota. Un uso comune per omettere l'elemento Response quando si utilizza ServiceCallout: per registrare a un sistema esterno.

 <Response>calloutResponse</Response> 

<Timeout> elemento

Il tempo in millisecondi durante il quale il criterio callout di servizio 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 HTTP 500, il criterio ha esito negativo e il proxy API entra in uno stato di errore, descritta in Gestione degli errori.

<Timeout>30000</Timeout>

&lt;HTTPTargetConnection&gt; elemento

Fornisce dettagli sul trasporto come URL, TLS/SSL e proprietà HTTP. Consulta le Riferimento alla configurazione di <TargetEndpoint>.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

&lt;HTTPTargetConnection&gt;/&lt;URL&gt; elemento

L'URL del servizio chiamato:

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

Puoi fornire una parte dell'URL in modo dinamico con una variabile. Tuttavia, la parte del protocollo l'URL http:// riportato di seguito non può essere specificato da una variabile. Nel prossimo esempio, utilizzerai una variabile per specificare il valore di una query :

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

In alternativa, imposta una parte del percorso dell'URL con una variabile:

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

Se vuoi utilizzare una variabile per specificare il dominio e la porta dell'URL, usa una sola variabile solo per il dominio e la porta e una seconda variabile per qualsiasi altra parte dell'URL:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

&lt;HTTPTargetConnection&gt;/&lt;SSLInfo&gt; elemento

La configurazione TLS/SSL al servizio di backend. Per informazioni sulla configurazione TLS/SSL, consulta Configurazione di TLS dal perimetro al backend (cloud e cloud privato) e alla configurazione dell'endpoint di destinazione TLS/SSL in Riferimento alla configurazione del proxy API.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>

Proprietà di trasporto HTTP al servizio di backend. Per ulteriori informazioni, vedi Riferimento per le proprietà degli endpoint.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>

&lt;HTTPTargetConnection&gt;/&lt;LoadBalancer&gt; elemento

Chiama uno o più server di destinazione ed esegui il bilanciamento del carico sui server. Vedi il target di chiamata di esempio di server nella sezione Esempi. Vedi anche Bilanciamento del carico tra backend server web. Vedi anche questa community che illustra i modi per chiamare i server di destinazione sia dai criteri relativi ai callout di servizio sia usando le regole di route.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>

&lt;LocalTargetConnection&gt; elemento

Specifica un proxy locale, ovvero un proxy nella stessa organizzazione e nello stesso ambiente, del target dei callout di servizio.

Per specificare ulteriormente il target, utilizza gli elementi <APIProxy> e <ProxyEndpoint> oppure l'elemento <Path>.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>

&lt;LocalTargetConnection&gt;/&lt;APIProxy&gt; elemento

Il nome di un proxy API che è la destinazione di una chiamata locale. Il proxy deve essere nello stesso organizzazione e ambiente come proxy che effettua la chiamata.

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

Insieme all'elemento <APIProxy>, includi il parametro Elemento <ProxyEndpoint> per specificare il nome dell'endpoint proxy che deve essere scelto come target per la chiamata.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection> 

&lt;LocalTargetConnection&gt;/&lt;ProxyEndpoint&gt; elemento

Il nome dell'endpoint proxy che deve essere la destinazione delle chiamate. Questo è un endpoint proxy in il proxy API specificato con l'elemento <APIProxy>.

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

&lt;LocalTargetConnection&gt;/&lt;Path&gt; elemento

Un percorso dell'endpoint scelto come target. L'endpoint deve fare riferimento a un proxy nello stesso organizzazione e ambiente come proxy che effettua la chiamata.

Usa questa opzione al posto di una coppia <APIProxy>/<ProxyEndpoint> quando non conoscere (o non poter fare affidamento) sul nome del proxy. Il percorso potrebbe essere un obiettivo affidabile.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>

Schemi

Variabili di flusso

Le variabili di flusso consentono il comportamento dinamico di criteri e flussi in fase di runtime, in base a HTTP intestazioni, contenuti dei messaggi o contesto di Flow. Sono disponibili le seguenti variabili di flusso predefinite dopo l'esecuzione del criterio callout di servizio. Per ulteriori informazioni sulle variabili di flusso, consulta Riferimento per le variabili.

I callout di servizio hanno richieste e risposte proprie e puoi accedere a questi dati tramite come la codifica one-hot delle variabili categoriche. Poiché il messaggio principale utilizza request.* e response.*, utilizza i prefissi di variabile myrequest.* e calloutResponse.* (i valori predefiniti nella configurazione del callout di servizio) per ricevere i dati dei messaggi specifici del callout di servizio. Il primo esempio nella tabella seguente mostra come ottenere le intestazioni HTTP nel callout di servizio.

Errori

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

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

Fault variables

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

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="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

Argomenti correlati

• Generare o modificare i messaggi: Assegna criterio ai messaggi
• Estrazione di variabili: Estrai variabili norme
• Variabili: variabili riferimento
• Configurazione TLS/SSL
  • Configurazione TLS da perimetro al backend (cloud e cloud privato)
  • "Configurazione endpoint di destinazione TLS/SSL" in Informazioni di riferimento sulla configurazione del proxy API
• Proprietà di trasporto HTTP: riferimento sulle proprietà endpoint
• Alternativa al callout di servizio: HTTPClient scritto in JavaScript, consulta Modello a oggetti JavaScript