Как использовать композицию правил

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

Ниже приведено краткое описание элементов этих правил. Подробнее о правилах в отношении сообщений, назначаемых пользователям…

• <AssignMessage name> – позволяет задать название для этих правил. Это название используется, когда на правило ссылаются в процессе.
• <AssignTo> – создает именованную переменную GeocodingRequest. Эта переменная содержит объект запроса, который будет отправлен на серверную часть правилом ServiceCallout.
• <QueryParams> – задает параметры запроса, необходимые для вызова API на сервере. В этом случае Geocoding API должен знать местоположение, которое выражается почтовым индексом и идентификатором страны. Пользователь приложения предоставляет эту информацию, а мы просто извлекаем ее. Параметр sensor обязателен для API и может иметь значение true или false. В нашем случае он имеет значение false.
• <Verb> – в этом случае мы отправляем простой GET-запрос к API.
• <AssignVariable> – переменные, в которых хранятся значения, передаваемые в API. В этом примере переменные будут доступны позже в ответе, возвращенном клиенту.

Отправка запроса с помощью ServiceCallout

Следующим шагом в последовательности создания правил является создание правила ServiceCallout. Правило ServiceCallout, приведенное ниже, отправляет объект запроса, созданный в предыдущем правиле AssignMessage, в сервис геокодирования Google и сохраняет результат в переменной GeocodingResponse.

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

Ниже приведено краткое описание элементов этих правил.

• <ServiceCallout> – как и в предыдущих правилах, у этого есть название.
• <Request variable> – переменная, созданная в правиле AssignMessage. Он содержит запрос, отправляемый в API внутреннего сервиса.
• <Response> – элемент, в котором указывается переменная, в которой хранится ответ. Как вы увидите, эта переменная будет позже использоваться правилом ExtractVariables.
• <HTTPTargetConnection> – указывает целевой URL внутреннего API. В этом случае мы указываем, что API должен вернуть ответ JSON.

Теперь у нас есть два правила: одно указывает, какая информация нужна для использования внутреннего API (Geocoding API от Google), а второе отправляет запрос во внутренний API. Затем мы обработаем ответ.

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

Ключевые элементы правила ExtractVariable:

• <ExtractVariables name> – название политики используется для ссылки на нее в потоке.
• <Source> – указывает переменную ответа, созданную в правиле ServiceCallout. Это переменная, из которой извлекаются данные.
• <VariablePrefix> – префикс переменной задает пространство имен для других переменных, созданных в этой политике. Префикс может быть любым именем, кроме зарезервированных имен, определенных стандартными переменными Edge.
• <JSONPayload> – этот элемент извлекает из ответа нужные нам данные и помещает их в именованные переменные. На самом деле Geocoding API возвращает гораздо больше информации, чем широта и долгота. Однако для этого примера нам нужны только эти значения. Полный текст ответа JSON, возвращаемого Geocoding API, можно найти в документации по API. Значения geometry.location.lat и geometry.location.lng – это всего лишь два из множества полей в возвращаемом объекте JSON.

Это может быть не очевидно, но важно понимать, что ExtractVariables создает две переменные, названия которых состоят из префикса переменной (geocoderesponse) и фактических названий переменных, указанных в правиле. Эти переменные хранятся в прокси-сервере API и будут доступны другим правилам в потоке прокси, как вы увидите. Переменные:

• geocoderesponse.latitude
• geocoderesponse.longitude

Большая часть работы уже выполнена. Мы создали композицию из трех правил, которые формируют запрос, вызывают API на сервере и анализируют возвращенные данные JSON. На заключительном этапе мы передадим данные из этой части потока в другое правило AssignMessage, вызовем второй внутренний API (Google Elevation API) и вернем объединенные данные разработчику приложения.

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

Если вы изучите Google Elevation API, то увидите, что он принимает два параметра запроса. Первый называется locations, а его значение – широта и долгота (значения разделены запятыми). Другой параметр – sensor. Он обязателен и должен иметь значение true или false. Важно отметить, что созданный здесь запрос не требует ServiceCallout. На этом этапе нам не нужно вызывать второй API из ServiceCallout, поскольку мы можем вызвать внутренний API из TargetEndpoint прокси. Если подумать, у нас есть все необходимые данные для вызова Google Elevations API. Запрос, созданный на этом этапе, не требует ServiceCallout, поскольку он был создан для основного конвейера запросов и будет просто перенаправлен ProxyEndpoint в TargetEndpoint в соответствии с RouteRule, настроенным для этого прокси-сервера API. TargetEndpoint управляет подключением к удаленному API. (Напомним, что URL для Elevation API задан в HTTPConnection для TargetEndpoint. Elevation API. Параметры QueryParams, которые мы сохранили ранее (country и postalcode), больше не нужны, поэтому мы их удаляем.

Небольшая пауза: возвращение к процессу

Возможно, вы задаетесь вопросом, почему мы не создаем ещё одно правило ServiceCallout. Ведь мы создали ещё одно сообщение. Как это сообщение отправляется в целевой сервис, Google Elevation API? Ответ содержится в элементе <RouteRule> потока. <RouteRule> указывает, что делать с оставшимися сообщениями запроса после выполнения части <Request> потока. Конечная точка TargetEndpoint, указанная в этом правиле <RouteRule>, сообщает прокси-серверу API, что сообщение нужно доставить в http://maps.googleapis.com/maps/api/elevation/xml.

Если вы скачали образец прокси-сервера API, то XML-файл TargetProxy можно найти в файле 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>

Теперь нам нужно обработать ответ от Google Elevation API.

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

Ответ содержит геокодированное местоположение центра почтового индекса, предоставленного конечным пользователем приложения, а также высоту над уровнем моря в этом геокодированном местоположении. Данные были получены из двух бэкенд-API, объединены с правилами, подключенными к прокси-серверу API, и возвращены клиенту в одном ответе.

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

Сводка

В этом разделе рассказывалось, как использовать шаблон композиции правил для создания сводки данных из нескольких источников на стороне сервера. Композиция правил – это распространенный подход, используемый при разработке прокси API для добавления в API новых функций.