Richtlinienzusammensetzung verwenden

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

Im Folgenden werden die Bestandteile dieser Richtlinie kurz beschrieben. Weitere Informationen zu dieser Richtlinie finden Sie unter Nachrichtenrichtlinie zuweisen.

• <AssignMessage name>: Gibt dieser Richtlinie einen Namen. Der Name wird verwendet, wenn in einem Ablauf auf die Richtlinie verwiesen wird.
• <AssignTo>: Erstellt eine benannte Variable namens GeocodingRequest. Diese Variable kapselt das Anfrageobjekt, das von der ServiceCallout-Richtlinie an das Back-End gesendet wird.
• <QueryParams>: Legt die Abfrageparameter fest, die vom Back-End-API-Aufruf benötigt werden. In diesem Fall muss die Geocoding API den Standort kennen, der mit einer Postleitzahl und einer Länder-ID ausgedrückt wird. Der App-Nutzer stellt diese Informationen bereit und wir extrahieren sie einfach hier. Der Parameter sensor wird von der API benötigt und ist entweder „true“ oder „false“. Wir hartcodieren ihn hier einfach mit „false“.
• <Verb>: In diesem Fall stellen wir eine einfache GET-Anfrage an die API.
• <AssignVariable>: In diesen Variablen werden die Werte gespeichert, die an die API übergeben werden. In diesem Beispiel wird später in der an den Client zurückgegebenen Antwort auf die Variablen zugegriffen.

Anfrage mit ServiceCallout senden

Der nächste Schritt in der Sequenz zur Richtlinienzusammensetzung besteht darin, eine ServiceCallout-Richtlinie zu erstellen. Die unten aufgeführte ServiceCallout-Richtlinie sendet das Anfrageobjekt, das in der vorherigen AttributionMessage-Richtlinie erstellt wurde, an den Google Geocoding-Dienst und speichert das Ergebnis in einer Variablen namens „GeocodingResponse“.

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

Im Folgenden finden Sie eine kurze Beschreibung der Bestandteile dieser Richtlinie.

• <ServiceCallout>: Wie die vorherige Richtlinie hat auch diese einen Namen.
• <Request variable> – Dies ist die Variable, die in derAssignMessage-Richtlinie erstellt wurde. Sie kapselt die Anfrage an die Back-End-API.
• <Response>: Dieses Element benennt eine Variable, in der die Antwort gespeichert wird. Wie Sie sehen, wird später von der Richtlinie „ExtractVariables“ auf diese Variable zugegriffen.
• <HTTPTargetConnection> – Gibt die Ziel-URL der Back-End-API an. In diesem Fall geben wir an, dass die API eine JSON-Antwort zurückgibt.

Jetzt haben wir zwei Richtlinien: die eine gibt die Anfrageinformationen an, die für die Verwendung der Back-End API (Geocoding API von Google) erforderlich sind, und die zweite, die die Anfrage an die Back-End API sendet. Als Nächstes bearbeiten wir die Antwort.

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

Die wichtigsten Elemente der ExtractVariable-Richtlinie sind:

• <ExtractVariables name>: Auch hier wird der Richtlinienname verwendet, um auf die Richtlinie zu verweisen, wenn sie in einem Ablauf verwendet wird.
• <Source>: Gibt die Antwortvariable an, die in der ServiceCallout-Richtlinie erstellt wurde. Das ist die Variable, aus der diese Richtlinie Daten extrahiert.
• <VariablePrefix>: Das Variablenpräfix gibt einen Namespace für andere in dieser Richtlinie erstellte Variablen an. Das Präfix kann ein beliebiger Name sein, mit Ausnahme der reservierten Namen, die durch die vordefinierten Variablen von Edge definiert sind.
• <JSONPayload>: Dieses Element ruft die für uns interessanten Antwortdaten ab und fügt sie in benannte Variablen ein. Die Geocoding API gibt viel mehr Informationen zurück als Breiten- und Längengrade. Dies sind jedoch die einzigen Werte, die wir für dieses Beispiel benötigen. Eine vollständige Darstellung der von der Geocoding API zurückgegebenen JSON-Daten finden Sie in der API-Dokumentation. Die Werte von geometry.location.lat und geomet.location.lng sind einfach zwei von vielen Feldern im zurückgegebenen JSON-Objekt.

Es mag nicht offensichtlich sein, aber es ist wichtig zu erkennen, dass ExtractVariables zwei Variablen erzeugt, deren Namen aus dem Variablenpräfix (georesponse) und den tatsächlichen Variablennamen bestehen, die in der Richtlinie festgelegt sind. Diese Variablen werden im API-Proxy gespeichert und stehen anderen Richtlinien innerhalb des Proxy-Ablaufs zur Verfügung, wie Sie sehen werden. Die Variablen sind:

• geocoderesponse.latitude
• geocoderesponse.longitude

Der Großteil der Arbeit ist jetzt erledigt. Wir haben eine Kombination aus drei Richtlinien erstellt, die eine Anfrage bilden, eine Back-End-API aufrufen und die zurückgegebenen JSON-Daten parsen. In den letzten Schritten speisen wir Daten aus diesem Teil des Ablaufs in eine andereAssignMessage-Richtlinie ein, rufen die zweite Back-End-API (Google Elevation API) auf und geben die aggregierten Daten an den App-Entwickler zurück.

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

Wenn Sie das Google Elevation API untersuchen, werden Sie feststellen, dass es zwei Abfrageparameter benötigt. Die erste heißt locations und hat den Breiten- und Längengrad (durch Kommas getrennte Werte). Der andere Parameter ist sensor. Dieser ist erforderlich und muss entweder wahr oder falsch sein. Das Wichtigste an dieser Stelle ist, dass für die hier erstellte Anfragenachricht kein ServiceCallout erforderlich ist. Die zweite API muss nicht mehr über ein ServiceCallout aufgerufen werden, da wir die Back-End-API über den TargetEndpoint des Proxys aufrufen können. Wenn Sie darüber nachdenken, haben wir alle Daten, die wir zum Aufrufen der Google Elevations API benötigen. Die in diesem Schritt generierte Anfragenachricht erfordert kein ServiceCallout, da die für die Hauptanfragepipeline generierte Anfrage einfach vom ProxyEndpoint an den TargetEndpoint weitergeleitet wird. Dies geschieht gemäß der für diesen API-Proxy konfigurierten RouteRule. Der TargetEndpoint verwaltet die Verbindung mit der Remote-API. (Denken Sie daran, dass die URL für die Elevation API in der HTTPConnection für den TargetEndpoint definiert ist. Elevation API-Dokumentation. Die zuvor gespeicherten Abfrageparameter country und postalcode werden nicht mehr benötigt. Deshalb entfernen wir sie hier.

Kurze Pause: Zurück zum Flow

An dieser Stelle fragen Sie sich vielleicht, warum wir keine weitere ServiceCallout-Richtlinie erstellen. Schließlich haben wir eine weitere Nachricht erstellt. Wie wird diese Nachricht an das Ziel gesendet, die Google Elevation API? Die Antwort befindet sich im <RouteRule>-Element des Ablaufs. <RouteRule> gibt an, was mit den verbleibenden Anfragenachrichten geschehen soll, nachdem der <Request>-Teil des Ablaufs ausgeführt wurde. Der in dieser <RouteRule> angegebene TargetEndpoint weist den API-Proxy an, die Nachricht an http://maps.googleapis.com/maps/api/elevation/xml zuzustellen.

Wenn Sie den API-Beispiel-Proxy heruntergeladen haben, finden Sie die TargetProxy-XML in der Datei 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>

Jetzt müssen wir nur noch die Antwort der Google Elevation API verarbeiten. Das ist alles.

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

Die Antwort enthält den vom App-Endnutzer angegebenen Ort für die Mitte der Postleitzahl, kombiniert mit der Höhe an diesem geocodierten Standort. Die Daten wurden von zwei Back-End-APIs abgerufen, mit Richtlinien verknüpft, die an den API-Proxy angehängt waren, und in einer einzigen Antwort an den Client zurückgegeben.

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

Zusammenfassung

In diesem Cookbook-Thema wurde erläutert, wie mithilfe des Richtlinienzusammensetzungsmusters ein Mashup von Daten aus mehreren Back-End-Quellen erstellt wird. Die Richtlinienzusammensetzung ist ein gängiges Muster, das bei der API-Proxy-Entwicklung zum Hinzufügen von Creative-Funktionen zu Ihrer API verwendet wird.