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>

Ecco una breve descrizione degli elementi di questa policy. Puoi saperne di più su questa policy in Policy Assign Message.

• <AssignMessage name> - Assegna un nome a questa policy. Il nome viene utilizzato quando si fa riferimento alla policy in un flusso.
• <AssignTo> - Crea una variabile denominata GeocodingRequest. Questa variabile incapsula l'oggetto della richiesta che verrà inviato al backend dalla policy 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 e noi le estraiamo semplicemente qui. Il parametro sensor è richiesto dall'API e può essere true o false. Qui lo codifichiamo come false.
• <Verb> - In questo caso, stiamo effettuando una semplice richiesta GET all' API.
• <AssignVariable> - Queste variabili memorizzano i valori che stiamo passando all'API. In questo esempio, le variabili verranno utilizzate in un secondo momento nella risposta restituita al client.

Invia la richiesta con ServiceCallout

Il passaggio successivo nella sequenza di composizione delle policy è la creazione di una policy ServiceCallout. La policy ServiceCallout, elencata di seguito, invia l'oggetto della richiesta che abbiamo creato nella policy AssignMessage precedente 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>

Ecco una breve descrizione degli elementi di questa policy.

• <ServiceCallout> - Come la policy precedente, anche questa ha un nome.
• <Request variable> - Questa è la variabile creata nella policy AssignMessage. Incapsula la richiesta all'API di backend.
• <Response> - Questo elemento assegna un nome a una variabile in cui viene memorizzata la risposta è archiviata. Come vedrai, questa variabile verrà utilizzata in un secondo momento dalla policy ExtractVariables.
• <HTTPTargetConnection> - Specifica l'URL di destinazione dell'API di backend API. In questo caso, specifichiamo che l'API restituisce una risposta JSON.

Ora abbiamo due policy: una che specifica le informazioni sulla richiesta necessarie per utilizzare l'API di backend (l'API Geocoding di Google) e la seconda che invia effettivamente la richiesta all'API di backend. Ora gestiremo la 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 policy ExtractVariable sono:

• <ExtractVariables name> - Anche in questo caso, il nome della policy viene utilizzato per fare riferimento alla policy quando viene utilizzata in un flusso.
• <Source> - Specifica la variabile di risposta creata nella policy ServiceCallout. Questa è la variabile da cui questa policy estrae i dati.
• <VariablePrefix> - Il prefisso della variabile specifica uno spazio dei nomi per altre variabili create in questa policy. Il prefisso può essere qualsiasi nome, ad eccezione dei nomi riservati definiti dalle variabili predefinite di Edge's.
• <JSONPayload> - Questo elemento recupera i dati di risposta che ci interessano e li inserisce in variabili denominate. In realtà, l'API Geocoding restituisce molte più informazioni di latitudine e longitudine. Tuttavia, questi sono gli unici valori di cui abbiamo bisogno per questo esempio. Puoi vedere un rendering completo del JSON restituito dall'API Geocoding nella documentazione dell'API. I valori di geometry.location.lat e geometry.location.lng sono semplicemente due dei tanti campi dell'oggetto JSON restituito.

Potrebbe non essere ovvio, ma è importante notare che ExtractVariables produce due variabili i cui nomi sono costituiti dal prefisso della variabile (geocoderesponse) e dai nomi delle variabili effettivi specificati nella policy. Queste variabili vengono memorizzate nel proxy API e saranno disponibili per altre policy all'interno del flusso del proxy, come vedrai. Le variabili sono:

• geocoderesponse.latitude
• geocoderesponse.longitude

La maggior parte del lavoro è stata completata. Abbiamo creato una composizione di tre policy 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'altra policy AssignMessage, chiameremo la seconda API di backend (l'API Google Elevation) e restituiremo i dati combinati allo sviluppatore di 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, vedrai che accetta due parametri di query. Il primo si chiama locations e il suo valore è la latitudine e la longitudine (valori separati da virgole). L'altro parametro è sensor, che è obbligatorio e deve essere true o false. La cosa più importante da notare a questo punto è che il messaggio di richiesta che creiamo qui non richiede un ServiceCallout. Non è necessario chiamare la seconda API da un ServiceCallout a questo punto perché possiamo chiamare l'API di backend da TargetEndpoint del proxy. Se ci pensi, abbiamo tutti i dati necessari per chiamare l'API Google Elevation Il messaggio di richiesta generato in questo passaggio non richiede un ServiceCallout, poiché la richiesta generata per la pipeline di richiesta principale verrà semplicemente inoltrata da ProxyEndpoint a TargetEndpoint, seguendo la RouteRule configurata per questo proxy API. TargetEndpoint gestisce la connessione con l'API remota. Ricorda che l'URL dell'API Elevation è definito in HTTPConnection per TargetEndpoint. Documentazione dell'API Elevation se vuoi saperne di più. I parametri di query che abbiamo memorizzato in precedenza, country e postalcode, non sono più necessari, quindi li rimuoviamo qui.

Breve pausa: torna al flusso

A questo punto, potresti chiederti perché non stiamo creando un'altra policy ServiceCallout. Dopo tutto, abbiamo creato un altro messaggio. Come viene inviato questo messaggio 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 questo <RouteRule> indica al proxy API di inviare il messaggio a http://maps.googleapis.com/maps/api/elevation/xml.

Se hai scaricato il proxy API di esempio, puoi trovare il codice XML di 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 dell'API Google Elevation e abbiamo finito.

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

La risposta include la località geocodificata per il centro del codice postale fornito da l'utente finale dell'app, combinata con l'elevazione in quella località geocodificata. I dati sono stati recuperati da due API di backend, combinati con le policy collegate 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

Questo argomento del cookbook ha spiegato come utilizzare il pattern di composizione delle policy per creare un mashup di dati provenienti da più origini di backend. La composizione delle policy è un pattern comune utilizzato nello sviluppo di proxy API per aggiungere funzionalità creative all'API.