Norme sui callout di servizio

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Cosa

Le norme relative ai callout di servizio ti consentono di chiamare un altro servizio dal flusso proxy API. Puoi creare callout a un servizio esterno (ad esempio un endpoint di servizio RESTful esterno) o a servizi interni (ad esempio un proxy API nella stessa organizzazione e nello stesso ambiente).

• In un caso d'uso esterno, crei un callout a un'API di terze parti esterna al tuo proxy. La risposta dell'API di terze parti viene analizzata e inserita nel messaggio di risposta dell'API, arricchendo e integrando i dati per gli utenti finali dell'app. Puoi anche effettuare una richiesta utilizzando il criterio callout di servizio 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, questo potrebbe essere utile se hai un proxy che offre funzionalità discrete di basso livello 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 diversi altri proxy che espongono i dati ai client.

Il criterio supporta le richieste tramite HTTP e HTTPS.

Esempi

<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 puoi utilizzare una norma sui callout di servizio 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 da un catalogo al dettaglio di un partner e così via.

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

• Richiesta: l'opzione Assegna messaggio compila il messaggio di richiesta inviato al servizio remoto.

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

La tipica composizione delle norme sui callout di servizio prevede:

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

Consulta Utilizzo della composizione dei criteri per un proxy API di esempio completo che utilizza la norma Callout di servizio insieme alle norme 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>

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:

Elemento <DisplayName>

Utilizzalo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Elemento <Request>

Specifica la variabile contenente il messaggio di richiesta che viene inviato dal proxy API all'altro servizio. La variabile può essere creata da una norma precedente nel flusso oppure è possibile 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 norma Assegna messaggio.

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

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

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

In alternativa, puoi compilare il messaggio di richiesta inviato al servizio esterno nelle norme relative ai callout di servizio:

<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

Elemento <Request>/<OptimizeUnresolvedVariables>

Se impostato su true, il criterio ignora qualsiasi errore relativo alle variabili non risolto nella richiesta.

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

Elemento <Response>

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

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

Se questo elemento viene omesso, il proxy API non attende una risposta; l'esecuzione del flusso del proxy API continua con tutti i passaggi del flusso successivi. Inoltre, per indicare l'ovvio, senza alcun elemento Response, la risposta della destinazione non è disponibile per l'elaborazione nei passaggi successivi e il flusso proxy non può in alcun modo rilevare un errore nella chiamata remota. Utilizzo comune per omettere l'elemento Response quando si utilizza ServiceCallout: per registrare i messaggi in un sistema esterno.

 <Response>calloutResponse</Response> 

Elemento <Timeout>

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 errore HTTP 500, il criterio non riesce e il proxy API entra in stato di errore, come descritto in Gestione degli errori.

<Timeout>30000</Timeout>

Elemento <HTTPTargetConnection>

Fornisce dettagli sul trasporto come URL, TLS/SSL e proprietà HTTP. Consulta il riferimento per la configurazione di <TargetEndpoint>.

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

Elemento <HTTPTargetConnection>/<URL>

URL del servizio chiamato:

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

Puoi fornire dinamicamente una parte dell'URL con una variabile. Tuttavia, la parte relativa al protocollo dell'URL, http:// di seguito, non può essere specificata da una variabile. Nell'esempio successivo, utilizzerai una variabile per specificare il valore di un parametro di ricerca:

<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 un'altra variabile per qualsiasi altra parte dell'URL:

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

Elemento <HTTPTargetConnection>/<SSLInfo>

La configurazione TLS/SSL al servizio di backend. Per informazioni sulla configurazione TLS/SSL, consulta Configurazione di TLS da Edge al backend (cloud e cloud privato) e "Configurazione degli endpoint di destinazione TLS/SSL" nel riferimento sulla configurazione del proxy API.

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

Proprietà di trasporto HTTP al servizio di backend. Per maggiori informazioni, consulta Riferimento sulle 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>

Elemento <HTTPTargetConnection>/<LoadBalancer>

Chiama uno o più server di destinazione ed esegui il bilanciamento del carico su di essi. Consulta l'esempio di Server di destinazione delle chiamate nella sezione Esempi. Vedi anche Bilanciamento del carico tra server di backend. Consulta anche questo post della community che illustra i modi per chiamare i server di destinazione sia dalle norme relative ai callout di servizio sia dall'utilizzo delle regole di route.

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

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>

Elemento <LocalTargetConnection>/<APIProxy>

Il nome di un proxy API che è il target di una chiamata locale. Il proxy deve trovarsi nella stessa organizzazione e nello stesso ambiente del proxy che effettua la chiamata.

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

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

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

Elemento <LocalTargetConnection>/<ProxyEndpoint>

Il nome dell'endpoint proxy che dovrebbe essere il target delle chiamate. Questo è un endpoint proxy nel proxy API specificato con l'elemento <APIProxy>.

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

Elemento <LocalTargetConnection>/<Path>

Percorso dell'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 coppia invece di una coppia <APIProxy>/<ProxyEndpoint> quando non conosci o non puoi fare affidamento sul nome del proxy. Il percorso potrebbe essere un target affidabile.

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

Schema

Variabili di flusso

Le variabili di flusso consentono il comportamento dinamico dei criteri e dei flussi in fase di runtime, in base alle intestazioni HTTP, ai contenuti dei messaggi o al contesto del flusso. Le seguenti variabili di flusso predefinite sono disponibili dopo l'esecuzione di un criterio di callout di servizio. Per ulteriori informazioni sulle variabili di flusso, consulta le informazioni di riferimento sulle variabili.

I callout di servizio hanno richieste e risposte proprie 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 del callout di servizio) per ottenere i dati dei messaggi specifici per il 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 e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito.

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 maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.

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

• Genera o modifica i messaggi: Assegna criteri relativi ai messaggi
• Estrai variabili: criterio Estrai variabili
• Variabili: riferimento alle variabili
• Configurazione TLS/SSL
  • Configurazione di TLS da Edge al backend (cloud e cloud privato)
  • "Configurazione di TargetEndpoint TLS/SSL" nel riferimento alla configurazione del proxy API
• Proprietà di trasporto HTTP: riferimento sulle proprietà degli endpoint
• Alternativa al callout di servizio: HTTPClient scritto in JavaScript, consulta la sezione Modello di oggetti JavaScript