Политика ServiceCallout

Вы просматриваете документацию Apigee Edge .
Перейти к документации Apigee X. info

Что

Политика вызова сервиса позволяет вам вызывать другой сервис из потока API-прокси. Вы можете выполнять вызовы как к внешнему сервису (например, к внешней конечной точке RESTful-сервиса), так и к внутренним сервисам (например, к API-прокси в той же организации и среде).

• В случае внешнего использования вы обращаетесь к стороннему API, который находится вне вашего прокси-сервера. Ответ от стороннего API анализируется и вставляется в ответное сообщение вашего API, дополняя и «смешивая» данные для конечных пользователей приложения. Вы также можете сделать запрос, используя политику Service Callout в потоке запросов, а затем передать информацию в ответе целевой конечной точке прокси-сервера API.
• В другом варианте использования вы вызываете прокси-сервер, находящийся в той же организации и среде, что и тот, из которого вы звоните. Например, это может быть полезно, если у вас есть прокси-сервер, предоставляющий некоторую дискретную низкоуровневую функциональность, которую используют один или несколько других прокси-серверов. Например, прокси-сервер, предоставляющий операции создания/чтения/обновления/удаления с использованием внутреннего хранилища данных, может быть целевым прокси-сервером для нескольких других прокси-серверов, предоставляющих эти данные клиентам.

Политика поддерживает запросы по протоколам HTTP и HTTPS.

Образцы

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

О политике вызова службы

Существует множество сценариев, в которых можно использовать политику вызова сервиса в вашем API-прокси. Например, вы можете настроить API-прокси для вызовов внешнего сервиса для предоставления данных геолокации, отзывов клиентов, товаров из розничного каталога партнёра и т. д.

Выноска обычно используется с двумя другими политиками: «Назначить сообщение» и «Извлечь переменные».

• Запрос : Назначить сообщение заполняет сообщение-запрос, отправленное удаленной службе.

• Ответ : Извлечь переменные анализирует ответ и извлекает определенное содержимое.

Типичный состав политики вызова службы включает в себя:

1. Назначение политики сообщений : создание сообщения-запроса, заполнение заголовков HTTP, параметров запроса, установка HTTP-глагола и т. д.
2. Политика вызова службы : ссылается на сообщение, созданное политикой назначения сообщения, определяет целевой URL-адрес для внешнего вызова и определяет имя объекта ответа, который возвращает целевая служба.
   
   Для повышения производительности вы также можете кэшировать ответы Service Callout, как описано в этой теме сообщества Apigee: Как сохранить результаты политики ServiceCallout в кэше, а затем извлечь их из кэша?.
3. Политика извлечения переменных : обычно определяет выражение JSONPath или XPath, которое анализирует сообщение, сгенерированное вызовом службы. Затем политика устанавливает переменные, содержащие значения, полученные из ответа вызова службы.

Полный пример API-прокси, который использует политику вызова службы вместе с политиками назначения сообщения и извлечения переменных, см. в разделе Использование композиции политики .

Пользовательская обработка ошибок

Ссылка на элемент

Ниже приведены элементы и атрибуты, которые можно настроить в этой политике:

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

Атрибуты <ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Элемент <DisplayName>

Используйте в дополнение к атрибуту name , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

<DisplayName>Policy Display Name</DisplayName>

Элемент <Request>

Указывает переменную, содержащую сообщение запроса, которое отправляется прокси-сервером API другому сервису. Переменная может быть создана предыдущей политикой в ​​потоке или встроена в политику вызова сервиса.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

Синтаксис тегов <Remove> , <Copy> , <Add> и <Set> такой же, как для политики назначения сообщения .

Политика возвращает ошибку, если сообщение-запрос не может быть разрешено или имеет недопустимый тип сообщения-запроса.

В простейшем примере вы передаете переменную, содержащую сообщение запроса, которое было заполнено ранее в потоке прокси-сервера API:

<Request clearPayload="true" variable="myRequest"/>

Или вы можете заполнить сообщение-запрос, отправляемое внешней службе, непосредственно в политике вызова службы:

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

Атрибуты

Элемент <Request>/<IgnoreUnresolvedVariables>

Если задано значение true , политика игнорирует любые неразрешенные ошибки переменных в запросе.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

Элемент <Response>

Включите этот элемент, когда логика прокси-сервера API требует ответа от удаленного вызова для дальнейшей обработки.

При наличии этого элемента он определяет имя переменной, которая будет содержать ответное сообщение, полученное от внешней службы. Ответ от целевого объекта присваивается переменной только после успешного прочтения всего ответа политикой. Если удалённый вызов по какой-либо причине не выполняется, политика возвращает ошибку.

Если этот элемент пропущен, API-прокси не ожидает ответа; выполнение потока API-прокси продолжается на всех последующих этапах. Кроме того, очевидно, что без элемента Response ответ от целевого объекта недоступен для обработки на последующих этапах, и поток прокси не может обнаружить сбой в удалённом вызове. Обычный случай пропуска элемента Response при использовании ServiceCallout: для регистрации сообщений во внешней системе.

 <Response>calloutResponse</Response>

Элемент <Timeout>

Время в миллисекундах, в течение которого политика вызова службы будет ожидать ответа от целевого объекта. Это значение нельзя задать динамически во время выполнения. Если вызов службы достигает тайм-аута, возвращается код HTTP 500, политика не выполняется, а прокси-сервер API переходит в состояние ошибки, как описано в разделе Обработка сбоев .

<Timeout>30000</Timeout>

Элемент <HTTPTargetConnection>

Предоставляет сведения о транспорте, такие как URL, TLS/SSL и свойства HTTP. См. справочник по конфигурации <TargetEndpoint> .

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

Элемент <HTTPTargetConnection>/<URL>

URL-адрес вызываемой службы:

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

Вы можете динамически указать часть URL-адреса с помощью переменной. Однако часть URL-адреса, указывающая протокол (http://) , не может быть задана переменной. В следующем примере переменная используется для указания значения параметра запроса:

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

Или задайте часть пути URL с помощью переменной:

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

Если вы хотите использовать переменную для указания домена и порта URL-адреса, то используйте одну переменную только для домена и порта, а вторую переменную — для любой другой части URL-адреса:

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

Элемент <HTTPTargetConnection>/<SSLInfo>

Конфигурация TLS/SSL для бэкенд-сервиса. Справку по настройке TLS/SSL см. в разделах «Настройка TLS от Edge до бэкенда (облако и частное облако)» и «Настройка целевой конечной точки TLS/SSL» в справочнике по настройке прокси-сервера API .