Korzystanie z kompozycji zasad

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

Oto krótki opis elementów tej zasady. Więcej informacji o tej zasadzie znajdziesz w artykule Zasada Assign Message.

• <AssignMessage name> – nadaje tej zasadzie nazwę. Nazwa jest używana, gdy zasada jest przywoływana w przepływie.
• <AssignTo> – tworzy nazwaną zmienną o nazwie GeocodingRequest. Ta zmienna zawiera obiekt żądania, który zostanie wysłany do backendu przez zasadę ServiceCallout.
• <QueryParams> – ustawia parametry zapytania, które są potrzebne do wywołania interfejsu API backendu. W tym przypadku Geocoding API musi znać lokalizację, która jest wyrażona za pomocą kodu pocztowego i identyfikatora kraju. Użytkownik aplikacji podaje te informacje, a my po prostu je tutaj wyodrębniamy. Parametr sensor jest wymagany przez interfejs API i może mieć wartość true lub false. W tym przypadku ustawiamy go na stałe na false.
• <Verb> – w tym przypadku wysyłamy proste żądanie GET do interfejsu API.
• <AssignVariable> – te zmienne przechowują wartości, które przekazujemy do interfejsu API. W tym przykładzie zmienne będą dostępne później w odpowiedzi zwróconej do klienta.

Wysyłanie żądania za pomocą ServiceCallout

Następnym krokiem w sekwencji kompozycji zasad jest utworzenie zasady ServiceCallout. Zasada ServiceCallout, wymieniona poniżej, wysyła obiekt żądania utworzony w poprzedniej zasadzie AssignMessage do usługi Google Geocoding i zapisuje wynik w zmiennej o nazwie GeocodingResponse.

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

Oto krótki opis elementów tej zasady.

• <ServiceCallout> – podobnie jak poprzednia zasada, ta też ma nazwę.
• <Request variable> – jest to zmienna utworzona w zasadzie AssignMessage. Zawiera ona żądanie wysyłane do interfejsu API backendu.
• <Response> – ten element określa nazwę zmiennej, w której jest przechowywana odpowiedź. Jak zobaczysz, ta zmienna będzie później dostępna dla zasady ExtractVariables policy.
• <HTTPTargetConnection> – określa docelowy adres URL interfejsu API backendu API. W tym przypadku określamy, że interfejs API ma zwracać odpowiedź w formacie JSON.

Mamy teraz 2 zasady: pierwsza określa informacje o żądaniu potrzebne do korzystania z interfejsu API backendu (Google Geocoding API), a druga wysyła żądanie do interfejsu API backendu. Następnie zajmiemy się odpowiedzią.

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

Kluczowe elementy zasady ExtractVariable to:

• <ExtractVariables name> – nazwa zasady jest używana do odwoływania się do niej w przepływie.
• <Source> – określa zmienną odpowiedzi utworzoną w zasadzie ServiceCallout. Jest to zmienna, z której ta zasada wyodrębnia dane.
• <VariablePrefix> – prefiks zmiennej określa przestrzeń nazw dla innych zmiennych utworzonych w tej zasadzie. Prefiks może mieć dowolną nazwę, z wyjątkiem nazw zastrzeżonych zdefiniowanych przez predefiniowane zmienne Edge.
• <JSONPayload> – ten element pobiera dane odpowiedzi, które nas interesują, i umieszcza je w nazwanych zmiennych. W rzeczywistości Geocoding API zwraca znacznie więcej informacji niż szerokość i długość geograficzna. Jednak w tym przykładzie potrzebujemy tylko tych wartości. Pełną wersję JSON zwróconego przez Geocoding API znajdziesz w dokumentacji interfejsu API. Wartości geometry.location.lat i geometry.location.lng to tylko 2 z wielu pól w zwróconym obiekcie JSON.

Może to nie być oczywiste, ale ważne jest, aby zobaczyć, że ExtractVariables tworzy 2 zmienne, których nazwy składają się z prefiksu zmiennej (geocoderesponse) i rzeczywistych nazw zmiennych określonych w zasadzie. Te zmienne są przechowywane w proxy interfejsu API i będą dostępne dla innych zasad w przepływie proxy, jak zobaczysz. Zmienne to:

• geocoderesponse.latitude
• geocoderesponse.longitude

Większość pracy jest już wykonana. Utworzyliśmy kompozycję 3 zasad, które tworzą żądanie, wywołują interfejs API backendu i analizują zwrócone dane JSON. W ostatnich krokach przekierujemy dane z tej części przepływu do innej zasady AssignMessage, wywołamy drugi interfejs API backendu (Google Elevation API) i zwrócimy połączone dane do dewelopera aplikacji.

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

Jeśli sprawdzisz Google Elevation API, zobaczysz, że przyjmuje on 2 parametry zapytania. Pierwszy z nich to locations, a jego wartość to szerokość i długość geograficzna (wartości rozdzielone przecinkami). Drugi parametr to sensor, który jest wymagany i musi mieć wartość true lub false. W tym momencie najważniejsze jest, aby pamiętać, że utworzona tutaj wiadomość z żądaniem nie wymaga ServiceCallout. W tym momencie nie musimy wywoływać drugiego interfejsu API z ServiceCallout, ponieważ możemy wywołać interfejs API backendu z TargetEndpoint proxy. Jeśli się zastanowisz, mamy wszystkie dane potrzebne do wywołania Google Elevations API. Wiadomość z żądaniem wygenerowana w tym kroku nie wymaga ServiceCallout, ponieważ żądanie wygenerowane dla głównego potoku żądań zostanie po prostu przekazane przez ProxyEndpoint do TargetEndpoint zgodnie z regułą RouteRule skonfigurowaną dla tego proxy interfejsu API. TargetEndpoint zarządza połączeniem ze zdalnym interfejsem API. (Pamiętaj, że adres URL interfejsu Elevation API jest zdefiniowany w HTTPConnection dla TargetEndpoint. Dokumentacja Elevation API , jeśli chcesz dowiedzieć się więcej. Parametry QueryParams, które zostały wcześniej zapisane, country i postalcode, nie są już potrzebne, więc je usuwamy tutaj.

Krótka przerwa: powrót do przepływu

W tym momencie możesz się zastanawiać, dlaczego nie tworzymy kolejnej zasady ServiceCallout. W końcu utworzyliśmy kolejną wiadomość. Jak ta wiadomość jest wysyłana do celu, czyli Google Elevation API? Odpowiedź znajduje się w elemencie <RouteRule> przepływu. <RouteRule> określa, co zrobić z pozostałymi wiadomościami z żądaniem po wykonaniu części <Request> przepływu. TargetEndpoint określony przez ten element <RouteRule> informuje proxy interfejsu API, aby dostarczył wiadomość do http://maps.googleapis.com/maps/api/elevation/xml.

Jeśli masz pobrany przykładowy proxy interfejsu API, kod XML TargetProxy znajdziesz w pliku 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>

Teraz musimy tylko przetworzyć odpowiedź z Google Elevation API i gotowe.

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

Odpowiedź zawiera geokodowaną lokalizację środka kodu pocztowego podanego przez użytkownika aplikacji oraz wysokość w tej geokodowanej lokalizacji. Dane zostały pobrane z 2 interfejsów API backendu, połączone za pomocą zasad dołączonych do proxy interfejsu API i zwrócone do klienta w jednej odpowiedzi.

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

Podsumowanie

Z tego artykułu dowiesz się, jak używać wzorca kompozycji zasad do tworzenia mashupu danych z wielu źródeł backendu. Kompozycja zasad to powszechny wzorzec używany podczas tworzenia proxy interfejsu API do dodawania kreatywnych funkcji do interfejsu API.