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 cette règle. Pour en savoir plus sur cette règle, consultez la page Règle AssignMessage.

• <AssignMessage name> : attribue un nom à cette règle. Le nom est utilisé lorsque la règle est référencée dans un flux.
• <AssignTo> : crée une variable nommé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 de backend. Dans ce cas, l'API Geocoding doit connaître l'emplacement, qui est exprimé par un code postal et 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. Il est défini sur "true" ou "false". Nous le codons en dur sur "false" ici.
• <Verb> : dans ce cas, nous effectuons une simple requête GET auprès de l' API.
• <AssignVariable> : ces variables stockent les valeurs que nous transmettons à l'API. Dans cet exemple, les variables seront accessibles ultérieurement dans la réponse renvoyée au client.

Envoyer la requête avec ServiceCallout

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ègle AssignMessage 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 cette règle.

• <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. Elle encapsule la requête adressée à l'API de backend.
• <Response> : cet élément nomme une variable dans laquelle la réponse est stockée. Comme vous le verrez, cette variable sera accessible ultérieurement par la règle ExtractVariables policy.
• <HTTPTargetConnection> : spécifie l'URL cible de l'API de backend API. Dans ce cas, nous spécifions que l'API renvoie une réponse JSON.

Nous avons maintenant deux règles : une qui spécifie les informations de requête nécessaires pour utiliser l' API de backend (l'API Google Geocoding) et une seconde qui envoie réellement la requête à l' API de backend. Ensuite, nous allons 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 cette règle extrait des 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's.
• <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. Toutefois, ce sont les seules valeurs dont nous avons besoin pour cet exemple. Vous pouvez voir un rendu complet du code JSON renvoyé par l'API Geocoding dans 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é.

Ce n'est peut-être pas évident, mais il est important de voir qu'ExtractVariables produit deux variables dont les noms se composent du préfixe de 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 plus grande partie du travail est maintenant terminée. Nous avons créé un composite de trois règles qui forment une requête, appellent une API de backend et analysent les données JSON renvoyées. Dans les dernières étapes, nous allons transmettre les données de cette partie du flux à une autre règle AssignMessage, appeler la deuxième API de backend (API Google Elevation) et renvoyer nos données combinées au développeur d’applications.

<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 verrez qu'elle accepte deux paramètres de requête. Le premier 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 être défini sur "true" ou "false". Le point le plus important à noter à ce stade est que le message de requête que nous créons ici ne nécessite pas de ServiceCallout. Nous n'avons pas besoin d'appeler la deuxième API à partir d'un ServiceCallout à ce stade, car nous pouvons appeler l'API de 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 de ServiceCallout, car la requête générée pour le pipeline de requête principal sera simplement transmise par le ProxyEndpoint au TargetEndpoint, en suivant la RouteRule configurée pour ce proxy d'API. Le TargetEndpoint gère la connexion avec l'API distante. (Rappelez-vous que l'URL de l'API Elevation est définie dans la HTTPConnection du TargetEndpoint. 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 une autre règle ServiceCallout. 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 une fois la partie <Request> de le flux exécuté. Le TargetEndpoint spécifié par cette <RouteRule> indique au proxy d'API de transmettre 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 code 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.

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

La réponse inclut l'emplacement géocodé du centre du code postal fourni par l'utilisateur final de l'application, combiné à l'altitude de cet emplacement géocodé. Les données ont été récupérées à partir de deux API de backend, combinées à l'aide de règles associées au proxy d'API et renvoyées au client dans 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 livre de recettes explique comment utiliser le modèle de composition de règles pour créer un mashup de données provenant de plusieurs sources de 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 créativité à votre API.