Norme relative a ServiceCallout

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Cosa

Il criterio Service Callout ti consente di chiamare un altro servizio dal flusso del proxy API. Puoi effettuare chiamate a un servizio esterno (ad esempio un endpoint di servizio RESTful esterno) o a servizi interni (ad esempio un proxy API nella stessa organizzazione e nello stesso ambiente).

• In un caso d'uso esterno, effettui un callout a un'API di terze parti esterna al tuo proxy. La risposta dell'API di terze parti viene analizzata e inserita nel messaggio di risposta dell'API, arricchendo e combinando i dati per gli utenti finali dell'app. Puoi anche effettuare una richiesta utilizzando il criterio Service Callout nel flusso di richiesta, quindi passare le informazioni nella risposta a TargetEndpoint del proxy API.
• In un altro caso d'uso, chiami un proxy che si trova nella stessa organizzazione e nello stesso ambiente di quello da cui stai chiamando. Ad esempio, potresti trovare questa funzionalità utile quando hai un proxy che offre alcune funzionalità discrete di basso livello che uno o più altri proxy utilizzeranno. Ad esempio, un proxy che espone operazioni di creazione/lettura/aggiornamento/eliminazione con un datastore di backend potrebbe essere il proxy di destinazione per più proxy che espongono i dati ai client.

Il criterio supporta le richieste tramite HTTP e HTTPS.

Campioni

<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 sulla policy di callout del servizio

Esistono molti scenari in cui puoi utilizzare un criterio Service Callout nel tuo proxy API. Ad esempio, puoi configurare un proxy API per effettuare chiamate a un servizio esterno per fornire dati di geolocalizzazione, recensioni dei clienti, articoli del catalogo di vendita al dettaglio di un partner e così via.

Un callout viene in genere utilizzato con altre due norme: Assegna messaggio ed Estrai variabili.

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

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

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

1. Assegna criterio messaggio: crea un messaggio di richiesta, compila le intestazioni HTTP, i parametri di query, imposta il verbo HTTP e così via.
2. Policy Service Callout: fa riferimento a un messaggio creato dalla policy Assign Message, 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 di Service Callout, come descritto in questo thread della community Apigee: How can I store the results of the ServiceCallout policy in cache and later retrieve it from cache?.
3. Extract Variables policy: Typically defines a JSONPath or XPath expression that parses the message generated by the Service Callout. Il criterio imposta quindi le variabili contenenti i valori analizzati dalla risposta del callout del servizio.

Consulta la sezione Utilizzo della composizione delle norme per un proxy API di esempio completo che utilizza la norma Service Callout insieme alle norme Assign Message ed Extract Variables.

Gestione degli errori personalizzata

Riferimento elemento

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

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <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 del criterio:

&lt;DisplayName&gt; 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>

Elemento <Request>

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

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

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

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

In alternativa, puoi compilare il messaggio di richiesta inviato al servizio esterno nella stessa policy di callout del 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>/<IgnoreUnresolvedVariables>

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

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

Elemento <Response>

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

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

Se questo elemento viene omesso, il proxy API non attende una risposta; l'esecuzione del flusso del proxy API continua con i passaggi del flusso successivi. Inoltre, per ovvie ragioni, senza l'elemento Response, la risposta dalla destinazione non è disponibile per l'elaborazione da parte dei passaggi successivi e non è possibile rilevare un errore nella chiamata remota. Un utilizzo comune dell'omissione dell'elemento Response quando si utilizza ServiceCallout: registrare i messaggi in un sistema esterno.

 <Response>calloutResponse</Response>

Elemento <Timeout>

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

<Timeout>30000</Timeout>

Elemento <HTTPTargetConnection>

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

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

Elemento <HTTPTargetConnection>/<URL>

L'URL del servizio chiamato:

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

Puoi fornire parte dell'URL in modo dinamico con una variabile. Tuttavia, la parte del protocollo dell'URL, http:// di seguito, non può essere specificata da una variabile. Nell'esempio successivo, utilizzi una variabile per specificare il valore di un parametro di query:

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

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

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

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

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

Elemento <HTTPTargetConnection>/<SSLInfo>

La configurazione TLS/SSL del servizio di backend. Per assistenza sulla configurazione TLS/SSL, consulta Configurazione di TLS da Edge al backend (cloud e cloud privato) e "Configurazione di TargetEndpoint TLS/SSL" in Riferimento alla configurazione del proxy API.

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

Proprietà di trasporto HTTP al servizio di backend. Per saperne di più, consulta Riferimento per le proprietà degli endpoint.

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

Elemento <HTTPTargetConnection>/<LoadBalancer>

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

<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 la destinazione, 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 è la destinazione di una chiamata locale. Il proxy deve trovarsi nella stessa organizzazione e nello stesso ambiente del proxy che effettua la chiamata.

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

Oltre all'elemento <APIProxy>, includi l'elemento <ProxyEndpoint> per specificare il nome dell'endpoint proxy a cui deve essere indirizzata la chiamata.

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

Elemento <LocalTargetConnection>/<ProxyEndpoint>

Il nome dell'endpoint proxy che deve essere la destinazione delle chiamate. Si tratta di un endpoint proxy nel proxy API specificato con l'elemento <APIProxy>.

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

Elemento <LocalTargetConnection>/<Path>

Un percorso verso l'endpoint di destinazione. L'endpoint deve fare riferimento a un proxy nella stessa organizzazione e nello stesso ambiente del proxy che effettua la chiamata.

Utilizza questa opzione anziché 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>

Schemi

Variabili di flusso

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

I callout di servizio 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 del callout di servizio) per ottenere dati dei messaggi specifici per il callout di servizio. Il primo esempio nella tabella seguente mostra come ottenere le intestazioni HTTP nel Service Callout.

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 messaggi: assegnare il criterio per i messaggi
• Estrai variabili: Estrai variabili policy
• Variabili: Riferimento alle variabili
• Configurazione TLS/SSL
  • Configurazione di TLS da Edge al backend (cloud e Private Cloud)
  • "TLS/SSL TargetEndpoint Configuration" (Configurazione TargetEndpoint TLS/SSL) in Riferimento per la configurazione dei proxy API
• Proprietà di trasporto HTTP: Riferimento per le proprietà degli endpoint
• Alternativa al callout del servizio: HTTPClient scritto in JavaScript, vedi Modello oggetto JavaScript