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

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali del criterio:

<DisplayName> elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

<Request> elemento

Specifica la variabile contenente il messaggio di richiesta che viene inviato dal proxy API allo altro servizio. La variabile può essere creata da un criterio precedente nel flusso oppure puoi crearla in linea 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

Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

Errori di deployment

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

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

Esempio di risposta di errore

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

Esempio di regola di errore

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

Argomenti correlati

• Generare o modificare i messaggi: 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