Utiliser la composition de règles

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

Voici une brève description des éléments de ces règles. Pour en savoir plus sur cette règle, consultez la section Attribuer une règle de message.

• <AssignMessage name> : attribue un nom à cette règle. Ce nom est utilisé lorsque la règle est référencée dans un flux.
• <AssignTo> : crée une variable nommée appelée GeocodingRequest. Cette variable encapsule l'objet de requête qui sera envoyé au backend par la règle ServiceCallout.
• <QueryParams> : définit les paramètres de requête nécessaires à l'appel d'API backend. Dans ce cas, l'API Geocoding doit connaître le lieu, qui est exprimé à l'aide d'un code postal et d'un ID de pays. L'utilisateur de l'application fournit ces informations, et nous les extrayons simplement ici. Le paramètre sensor est requis par l'API. Sa valeur est "true" ou "false", et nous le coderons en dur sur "false".
• <Verb> : dans ce cas, nous envoyons une requête GET simple à l'API.
• <AssignVariable> - Ces variables stockent les valeurs que nous transmettons à l'API. Dans cet exemple, les variables sont accessibles ultérieurement dans la réponse renvoyée au client.

Envoyer la requête avec ServiceAppel

L'étape suivante de la séquence de composition de règles consiste à créer une règle ServiceCallout. La règle ServiceCallout, listée ci-dessous, envoie l'objet de requête que nous avons créé dans la règleAssignMessage précédente au service Google Geocoding et enregistre le résultat dans une variable appelée GeocodingResponse.

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

Voici une brève description des éléments de ces règles.

• <ServiceCallout> : comme la règle précédente, celle-ci a un nom.
• <Request variable> : il s'agit de la variable créée dans la règle "AssignMessage". Il encapsule la requête envoyée à l'API backend.
• <Response> : cet élément nomme une variable dans laquelle la réponse est stockée. Comme vous le verrez, la règle ExtractVariables permettra ultérieurement d'accéder à cette variable.
• <HTTPTargetConnection> : spécifie l'URL cible de l'API backend. Dans ce cas, nous indiquons que l'API renvoie une réponse JSON.

Nous avons maintenant deux règles, la première qui spécifie les informations de requête nécessaires pour utiliser l'API backend (API Geocoding de Google) et la seconde qui envoie réellement la requête à l'API backend. Nous allons maintenant gérer la réponse.

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

Les éléments clés de la règle ExtractVariable sont les suivants:

• <ExtractVariables name> : encore une fois, le nom de la règle est utilisé pour faire référence à la règle lorsqu'elle est utilisée dans un flux.
• <Source> : spécifie la variable de réponse que nous avons créée dans la règle ServiceCallout. Il s'agit de la variable à partir de laquelle la règle extrait les données.
• <VariablePrefix> - Le préfixe de variable spécifie un espace de noms pour les autres variables créées dans cette règle. Le préfixe peut être n'importe quel nom, à l'exception des noms réservés définis par les variables prédéfinies de Edge.
• <JSONPayload> : cet élément récupère les données de réponse qui nous intéressent et les place dans des variables nommées. En fait, l'API Geocoding renvoie beaucoup plus d'informations que la latitude et la longitude. Cependant, ce sont les seules valeurs dont nous avons besoin pour cet exemple. Pour voir le rendu complet du fichier JSON renvoyé par l'API Geocoding, consultez la documentation de l'API. Les valeurs de geometry.location.lat et geometry.location.lng ne sont que deux des nombreux champs de l'objet JSON renvoyé.

Bien que cela ne soit pas évident, il est important de constater qu'ExtractVariables produit deux variables dont les noms se composent du préfixe de la variable (geocoderesponse) et des noms de variables réels spécifiés dans la règle. Ces variables sont stockées dans le proxy d'API et seront disponibles pour d'autres règles dans le flux de proxy, comme vous le verrez. Les variables sont les suivantes:

• geocoderesponse.latitude
• geocoderesponse.longitude

La majeure partie du travail est maintenant terminée. Nous avons créé un composite de trois règles qui forment une requête, appellent une API backend et analysent les données JSON renvoyées. Au cours des dernières étapes, nous allons transmettre les données de cette partie du flux à une autre règleAssignMessage, appeler la deuxième API backend (API Google Elevation) et renvoyer nos données combinées au développeur de l'application.

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

Si vous examinez l'API Google Elevation, vous constaterez qu'elle nécessite deux paramètres de requête. La première s'appelle locations et sa valeur est la latitude et la longitude (valeurs séparées par une virgule). L'autre paramètre est sensor, qui est obligatoire et doit avoir la valeur "true" ou "false". La chose la plus importante à noter à ce stade est que le message de requête que nous créons ici ne nécessite pas d'Appel de service. À ce stade, il n'est pas nécessaire d'appeler la deuxième API à partir d'un ServiceCallout, car nous pouvons appeler l'API backend à partir du TargetEndpoint du proxy. Si vous y réfléchissez, nous disposons de toutes les données dont nous avons besoin pour appeler l'API Google Elevations. Le message de requête généré à cette étape ne nécessite pas d'objet ServiceCallout, car la requête générée pour le pipeline de requêtes principal sera simplement transférée par ProxyEndpoint à TargetEndpoint, selon la règle RouteRule configurée pour ce proxy d'API. TargetEndpoint gère la connexion avec l'API distante. (Rappelez-vous que l'URL de l'API d'élévation est définie dans la classe HTTPConnection du point de terminaison cible. la documentation de l'API Elevation si vous souhaitez en savoir plus. Les QueryParams que nous avons stockés précédemment, country et postalcode, ne sont plus nécessaires. Nous les supprimons donc ici.

Brève pause: retour au flux

À ce stade, vous vous demandez peut-être pourquoi nous ne créons pas d'autres règles ServiceCall. Après tout, nous avons créé un autre message. Comment ce message est-il envoyé à la cible, l'API Google Elevation ? La réponse se trouve dans l'élément <RouteRule> du flux. <RouteRule> spécifie ce qu'il faut faire avec les messages de requête restants après l'exécution de la partie <Request> du flux. Le TargetEndpoint spécifié par cette <RouteRule> indique au proxy d'API de distribuer le message à http://maps.googleapis.com/maps/api/elevation/xml.

Si vous avez téléchargé l'exemple de proxy d'API, vous trouverez le fichier XML TargetProxy dans le fichier 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>

Il ne nous reste plus qu'à traiter la réponse de l'API Google Elevation, puis nous avons terminé.

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

La réponse inclut la position géocodée pour le centre du code postal fourni par l'utilisateur final de l'application, combinée à l'altitude à cette position géocodée. Les données ont été extraites de deux API backend, fusionnées avec les stratégies associées au proxy d'API, puis renvoyées au client en une seule réponse.

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

Résumé

Cette rubrique de ce livre de recettes explique comment utiliser le modèle de composition de règles pour créer un mélange de données provenant de plusieurs sources backend. La composition de règles est un modèle courant utilisé dans le développement de proxys d'API pour ajouter des fonctionnalités de création à votre API.