Использование композиции политики

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

Ниже приведено краткое описание элементов этой политики. Более подробную информацию об этой политике можно найти в разделе «Политика назначения сообщений» .

• <Имя присваиваемого сообщения> - Задает имя этой политике. Имя используется, когда политика используется в потоке.
• <AssignTo> - Создает именованную переменную с именем GeocodingRequest. Эта переменная инкапсулирует объект запроса, который будет отправлен на серверную часть политикой ServiceCallout.
• <QueryParams> — Задает параметры запроса, необходимые для вызова API бэкэнда. В данном случае API геокодирования необходимо знать местоположение, которое выражается почтовым индексом и идентификатором страны. Пользователь приложения предоставляет эту информацию, и мы просто извлекаем ее здесь. Параметр sensor является обязательным для API и может принимать значения true или false, поэтому мы просто задаем его значение false.
• <Глагол> - В данном случае мы выполняем простой 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> - Как и в случае с предыдущей политикой, у этой есть название.
• <Переменная запроса> - Это переменная, созданная в политике AssignMessage. Она инкапсулирует запрос, направляемый к бэкэнд-API.
• <Response> — Этот элемент задаёт имя переменной, в которой хранится ответ. Как вы увидите, доступ к этой переменной будет позже использован политикой ExtractVariables.
• <HTTPTargetConnection> — указывает целевой URL-адрес бэкэнд-API. В данном случае мы указываем, что API должен возвращать JSON-ответ.

Теперь у нас есть две политики: одна определяет информацию запроса, необходимую для использования бэкэнд-API (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:

• <Имя извлекаемых переменных> - Опять же, имя политики используется для ссылки на политику при ее использовании в потоке.
• <Источник> - Указывает переменную ответа, которую мы создали в политике ServiceCallout. Именно из этой переменной данная политика извлекает данные.
• <VariablePrefix> - Префикс переменной задает пространство имен для других переменных, созданных в этой политике. Префикс может быть любым именем, за исключением зарезервированных имен, определенных предопределенными переменными Edge .
• <JSONPayload> — Этот элемент извлекает интересующие нас данные ответа и помещает их в именованные переменные. На самом деле, API геокодирования возвращает гораздо больше информации, чем широта и долгота. Однако для этого примера нам нужны только эти значения. Полное отображение JSON-данных, возвращаемых 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>

Если вы изучите API Google Elevation, вы увидите, что он принимает два параметра запроса. Первый называется locations , и его значение — широта и долгота (значения, разделенные запятыми). Другой параметр — sensor , который является обязательным и должен быть либо true, либо false. Самое важное, что следует отметить на этом этапе, — это то, что создаваемое нами сообщение запроса не требует вызова ServiceCallout. Нам не нужно вызывать второй API из ServiceCallout на данном этапе, потому что мы можем вызвать бэкэнд-API из TargetEndpoint прокси-сервера. Если подумать, у нас есть все необходимые данные для вызова API Google Elevation. Сообщение запроса, сгенерированное на этом шаге, не требует вызова ServiceCallout, поскольку запрос генерируется для основного конвейера запросов, и поэтому будет просто перенаправлен ProxyEndpoint в TargetEndpoint в соответствии с правилом маршрутизации, настроенным для этого API-прокси. TargetEndpoint управляет соединением с удаленным API. (Напомним, что URL-адрес для API повышения высоты определяется в HTTPConnection для TargetEndpoint. Дополнительную информацию можно найти в документации API повышения высоты. Параметры запроса, которые мы хранили ранее, 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>

Теперь нам осталось только обработать ответ от API Google Elevation, и всё готово.

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