Utilizzo della composizione dei criteri

<AssignMessage name="GenerateGeocodingRequest">
  <AssignTo createNew="true" type="request">GeocodingRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
      <QueryParam name="region">{request.queryparam.country}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <!-- Set variables for use in the final response -->
  <AssignVariable>
    <Name>PostalCode</Name>
    <Ref>request.queryparam.postalcode</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

Di seguito è riportata una breve descrizione degli elementi di queste norme. Per saperne di più su questo criterio, consulta l'articolo Assegnare criteri relativi ai messaggi.

• <AssignMessage name>: assegna un nome al criterio. Il nome viene utilizzato quando viene fatto riferimento al criterio in un flusso.
• <AssignTo>: crea una variabile con nome denominata GeocodingRequest. Questa variabile incapsula l'oggetto della richiesta che verrà inviato al backend dal criterio ServiceCallout.
• <QueryParams> - Imposta i parametri di query necessari per la chiamata API di backend. In questo caso, l'API Geocoding deve conoscere la località, espressa con un codice postale, e un ID paese. L'utente dell'app fornisce queste informazioni, che ci limitiamo a estrarre qui. Il parametro sensor è obbligatorio dall'API ed è true o false; in questo caso lo impostiamo come hardcoded su false.
• <Verb> - In questo caso, stiamo effettuando una semplice richiesta GET all'API.
• <AssignVariable>: queste variabili memorizzano i valori che passiamo all'API. In questo esempio, si accederà alle variabili in un secondo momento nella risposta restituita al client.

Invia la richiesta con ServiceCallout

Il passaggio successivo nella sequenza di composizione delle norme consiste nel creare una norma ServiceCallout. Il criterio ServiceCallout, elencato di seguito, invia l'oggetto di richiesta che abbiamo creato nel precedente criterio di AssegnaMessage al servizio Google Geocoding e salva il risultato in una variabile denominata GeocodingResponse.

<ServiceCallout name="ExecuteGeocodingRequest">
  <Request variable="GeocodingRequest"/>
  <Response>GeocodingResponse</Response>
  <HTTPTargetConnection>
    <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Di seguito è riportata una breve descrizione degli elementi di queste norme.

• <ServiceCallout>: come nella norma precedente, anche questa ha un nome.
• <Variabile di richiesta>: questa è la variabile creata nel criterio di AssegnaMessage. Incapsula la richiesta inviata all'API di backend.
• <Response> - Questo elemento denomina una variabile in cui viene archiviata la risposta. Come puoi notare, il criterio ExtractVariables accederà a questa variabile in un secondo momento.
• <HTTPTargetConnection>: specifica l'URL di destinazione dell'API di backend. In questo caso, specifichiamo che l'API restituisce una risposta JSON.

Ora abbiamo due criteri: uno che specifica le informazioni della richiesta necessarie per utilizzare l'API di backend (l'API Geocoding di Google) e il secondo che invia effettivamente la richiesta all'API di backend. Ora ci occuperemo della risposta.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>GeocodingResponse</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
       <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
       <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Gli elementi chiave della norma ExtractVariable sono:

• <ExtractVariables name> - Anche in questo caso, il nome del criterio viene utilizzato per fare riferimento al criterio quando viene utilizzato in un flusso.
• <Source> - Specifica la variabile di risposta creata nelle norme relative ai callout di servizio. Questa è la variabile da cui il criterio estrae i dati.
• <VariablePrefix>: il prefisso della variabile specifica uno spazio dei nomi per altre variabili create in questo criterio. Il prefisso può essere qualsiasi nome, ad eccezione dei nomi riservati definiti dalle variabili predefinite di Edge.
• <JSONPayload>: questo elemento recupera i dati della risposta che ci interessano e li inserisce in variabili con nome. In effetti, l'API Geocoding restituisce molte più informazioni rispetto a latitudine e longitudine. Tuttavia, questi sono gli unici valori necessari per questo campione. Puoi vedere un rendering completo del JSON restituito dall'API Geocoding nella documentazione dell'API. I valori di geometria.location.lat e creative.location.lng sono semplicemente due dei numerosi campi nell'oggetto JSON restituito.

Potrebbe non essere ovvio, ma è importante vedere che ExtractVariables genera due variabili i cui nomi comprendono il prefisso di variabile (Geographicresponse) e i nomi effettivi delle variabili specificati nel criterio. Queste variabili sono memorizzate nel proxy API e saranno disponibili per altri criteri all'interno del flusso del proxy, come vedrai. Le variabili sono:

• geocoderesponse.latitude
• geocoderesponse.longitude

La maggior parte del lavoro è ora completata. Abbiamo creato un insieme di tre criteri che formano una richiesta, chiamano un'API di backend e analizzano i dati JSON restituiti. Nei passaggi finali, inseriremo i dati di questa parte del flusso in un altro criterio di AssegnaMessage, chiameremo la seconda API di backend (API Google Elevation) e restituiremo i dati combinati allo sviluppatore dell'app.

<AssignMessage name="AssignElevationParameters">
<Remove>
    <QueryParams>
      <QueryParam name="country"/>
      <QueryParam name="postalcode"/>
    </QueryParams>
  </Remove>
  <Set>
    <QueryParams>
      <QueryParam name="locations">{geocoderesponse.latitude},{geocoderesponse.longitude}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

Se esamini l'API Google Elevation, noterai che prende due parametri di query. Il primo si chiama locations e il suo valore è la latitudine e la longitudine (valori separati da virgola). L'altro parametro è sensor, obbligatorio e deve essere true o false. La cosa più importante da notare a questo punto è che il messaggio di richiesta creato qui non richiede un ServiceCallout. A questo punto non è necessario chiamare la seconda API da un ServiceCallout perché possiamo chiamare l'API di backend da TargetEndpoint del proxy. Se ci pensate, abbiamo tutti i dati che ci servono per chiamare l'API Google Elevations. Il messaggio di richiesta generato in questo passaggio non richiede un ServiceCallout, in quanto la richiesta generata per la pipeline di richiesta principale verrà inoltrata semplicemente da ProxyEndpoint a TargetEndpoint, seguendo la RouteRule configurata per questo proxy API. TargetEndpoint gestisce la connessione con l'API remota. Ricorda che l'URL per l'API elevazione è definito nella HTTPConnection per TargetEndpoint. Documentazione dell'API Elevation per saperne di più. I QueryParams che abbiamo archiviato in precedenza, country e postalcode, non sono più necessari, quindi li rimuoviamo qui.

Breve pausa: torna al flusso

A questo punto, vi chiederete perché non stiamo creando un'altra norma sui callout di servizio. Dopo tutto, abbiamo creato un altro messaggio. In che modo il messaggio viene inviato al target, l'API Google Elevation? La risposta si trova nell'elemento <RouteRule> del flusso. <RouteRule> specifica cosa fare con gli eventuali messaggi di richiesta rimanenti dopo l'esecuzione della parte <Request> del flusso. TargetEndpoint specificato da <RouteRule> indica al proxy API di consegnare il messaggio a http://maps.googleapis.com/maps/api/elevation/xml.

Se hai scaricato il proxy API di esempio, puoi trovare il valore XML TargetProxy nel file doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml.

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <!-- This is where we define the target. For this sample we just use a simple URL. -->
    <URL>http://maps.googleapis.com/maps/api/elevation/xml</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Ora dobbiamo solo elaborare la risposta dall'API Google Elevation, ed è fatta.

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

La risposta include la posizione geocodificata per il centro del codice postale fornito dall'utente finale dell'app, combinata con l'altitudine di quella posizione geocodificata. I dati sono stati recuperati da due API di backend, combinati con i criteri collegati al proxy API e restituiti al client in un'unica risposta.

{  
   "country":"us",
   "postalcode":"08008",
   "elevation":{  
      "meters":0.5045232,
      "feet":1.6552599030345978
   },
   "location":{  
      "latitude":39.75007129999999,
      "longitude":-74.1357407
   }
}

Riepilogo

In questo argomento del libro di ricette viene spiegato come utilizzare il pattern di composizione dei criteri per creare un mashup di dati da più origini backend. La composizione dei criteri è un pattern comune utilizzato nello sviluppo di proxy API per aggiungere funzionalità delle creatività all'API.