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 Przypisywanie zasad dotyczących wiadomości.

• <AssignMessage name> – nadaje tej zasadzie nazwę. Nazwa jest używana, gdy w procesie odwołuje się do tej zasady.
• <AssignTo> – tworzy zmienną nazwaną o nazwie GeocodingRequest. Ta zmienna zawiera obiekt żądania, który będzie wysyłany do backendu przez zasadę ServiceCallout.
• <QueryParams> – ustawia parametry zapytania wymagane przez wywołanie interfejsu API backendu. W tym przypadku interfejs 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 wyodrębniamy je w tym miejscu. Parametr sensor jest wymagany przez interfejs API i ma wartość prawda lub fałsz. Tutaj ustawiamy go na stałe na wartość false (fałsz).
• <Verb> – w tym przypadku tworzymy proste żądanie GET do interfejsu API.
• <AssignVariable> – te zmienne przechowują wartości, które przekazujemy do interfejsu API. W tym przykładzie zmienne zostaną udostępnione później w odpowiedzi zwróconej klientowi.

Wyślij prośbę z wyjaśnieniem usługi

Następnym krokiem w sekwencji tworzenia zasad jest utworzenie zasady ServiceCallout. Wymieniona poniżej zasada ServiceCallout 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> – tak jak poprzednia zasada, ta ma nazwę.
• <Request zmienna> – zmienna utworzona w zasadzie AssignMessage. Obejmuje żądanie trafiające do interfejsu API backendu.
• <Response> – ten element nadaje nazwę zmiennej, w której jest przechowywana odpowiedź. Jak zobaczysz, dostęp do tej zmiennej uzyska później zasada ExtractVariables.
• <HTTPTargetConnection> – określa docelowy adres URL interfejsu API backendu. W tym przypadku wskazujemy, że interfejs API zwraca odpowiedź JSON.

Mamy teraz 2 zasady. Jedna określa informacje o żądaniu potrzebne do użycia interfejsu API backendu (Google Geocoding API), a druga rzeczywiście wysyła żądanie do backendu API. 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:

• <nazwa zasady> – ponownie służy do odwoływania się do zasady, gdy jest używana w procesie.
• <Source> – określa zmienną odpowiedzi utworzoną w zasadzie ServiceCallout. To jest zmienna, z której ta zasada wyodrębnia dane.
• <VariablePrefix> – prefiks zmiennej określa przestrzeń nazw innych zmiennych utworzonych w tej zasadzie. Prefiks może być dowolną nazwą z wyjątkiem nazw zarezerwowanych zdefiniowanych przez zdefiniowane przez siebie zmienne Edge.
• <JSONPayload> – ten element pobiera dane odpowiedzi, które nas interesują, i umieszcza je w nazwanych zmiennych. W rzeczywistości interfejs Geocoding API zwraca znacznie więcej informacji niż szerokość i długość geograficzna. To jednak jedyne wartości, których potrzebujemy w tej próbce. Pełne wyrenderowanie pliku JSON zwróconego przez Geocoding API znajdziesz w dokumentacji interfejsu API. Wartości geometry.location.lat i geometry.location.lng to po prostu 2 z wielu pól w zwróconym obiekcie JSON.

Może to nie być oczywiste, ale trzeba pamiętać, że ExtractVariables tworzy 2 zmienne, których nazwy składają się z prefiksu zmiennej (odpowiedź geokodu) i rzeczywistych nazw zmiennych określonych w zasadach. Te zmienne są przechowywane na serwerze proxy interfejsu API i jak zobaczysz, będą dostępne dla innych zasad w ramach procesu serwera proxy. Zmienne to:

• geocoderesponse.latitude
• geocoderesponse.longitude

Większość pracy została wykonana. Utworzyliśmy zbiór 3 zasad, które tworzą żądanie, wywołują interfejs API backendu i analizują zwrócone dane JSON. W ostatnich krokach przekażemy dane z tej części procesu do innej zasady AssignMessage, wywołamy drugi interfejs API backendu (Google Elevation API) i zwrócimy połączone dane deweloperowi 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>

Po sprawdzeniu interfejsu Google Elevation API okazuje się, że używa on 2 parametrów zapytania. Pierwsza z nich to locations, a jej wartością jest szerokość i długość geograficzna (wartości rozdzielone przecinkami). Drugi parametr to sensor, który jest wymagany i musi mieć wartość prawda lub fałsz. Przede wszystkim pamiętaj, że tworzona tutaj wiadomość z żądaniem nie wymaga wywołania ServiceCallout. W tej chwili nie trzeba wywoływać drugiego interfejsu API z wywołania ServiceCallout, ponieważ możemy wywoływać interfejs API backendu z punktu końcowego docelowego punktu końcowego serwera proxy. Jeśli się nad tym zastanawiasz, mamy wszystkie dane potrzebne do wywołania Google Elevations API. Wiadomość żądania wygenerowana w tym kroku nie wymaga wywołania usługi, ponieważ żądanie wygenerowane dla głównego potoku żądań jest po prostu przekazywane przez punkt końcowy do punktu docelowego ProxyEndpoint zgodnie z regułą RouteRule skonfigurowaną dla tego serwera proxy interfejsu API. Docelowy punkt końcowy zarządza połączeniem ze zdalnym interfejsem API. Pamiętaj, że adres URL interfejsu API podniesienia jest zdefiniowany w punkcie HTTPConnection dla elementu TargetEndpoint. Dokumentacja interfejsu Elevation API, jeśli chcesz dowiedzieć się więcej. Zapisane wcześniej parametry QueryParams (country i postalcode) nie są już potrzebne, dlatego usuwamy je tutaj.

Krótkie wstrzymanie: powrót do procedury

być może zastanawiasz się, dlaczego nie tworzymy nowych zasad dotyczących objaśnienia usług. W końcu utworzyliśmy kolejną wiadomość. Jak ta wiadomość jest wysyłana do celu, czyli interfejsu Google Elevation API? Odpowiedź znajduje się w elemencie <RouteRule> w przepływie. <RouteRule> określa, co zrobić z wszelkimi pozostałymi komunikatami żądania po wykonaniu części <Request> przepływu. Punkt końcowy docelowego określony przez ten tag <RouteRule> informuje serwer proxy interfejsu API, aby dostarczyć wiadomość do http://maps.googleapis.com/maps/api/elevation/xml.

Jeśli pobrano przykładowy serwer proxy interfejsu API, plik 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 przetworzyć odpowiedź z interfejsu Google Elevation API.

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

Odpowiedź zawiera wskazaną geograficznie lokalizację pośrodku kodu pocztowego podaną przez użytkownika aplikacji oraz wysokość nad poziomem morza w tej lokalizacji geograficznej. Dane zostały pobrane z 2 interfejsów API backendu, połączone z zasadami przyłączonymi do serwera proxy interfejsu API i zwrócone klientowi w jednej odpowiedzi.

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

Podsumowanie

W tym temacie książki kucharskiej wyjaśniono, jak korzystać ze wzorca struktury zasad do tworzenia mashupów danych z różnych źródeł backendu. Kompozycja zasad to typowy wzorzec używany przy tworzeniu serwera proxy interfejsu API do dodawania funkcji kreacji do interfejsu API.