Политика ServiceCallout

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

Что

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

• В случае использования внешних сервисов вы обращаетесь к стороннему API, который находится вне вашего прокси-сервера. Ответ от стороннего API анализируется и вставляется в ответное сообщение вашего API, обогащая и «объединяя» данные для конечных пользователей приложения. Вы также можете отправить запрос, используя политику Service Callout в потоке запроса, а затем передать информацию из ответа в TargetEndpoint прокси-сервера 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-прокси для выполнения вызовов к внешнему сервису для предоставления данных о геолокации, отзывов клиентов, товаров из розничного каталога партнера и так далее.

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

• Функция Request : Assign Message заполняет сообщение запроса, отправляемое удаленному сервису.

• Ответ : Функция «Извлечение переменных» анализирует ответ и извлекает определенное содержимое.

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

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>

элемент <Таймаут>

Время в миллисекундах, в течение которого политика вызова сервиса будет ожидать ответа от целевого устройства. Это значение нельзя установить динамически во время выполнения. Если вызов сервиса завершается по истечении времени ожидания, возвращается 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-прокси .