Политика ServiceCallout

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

Что

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

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

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

• Запрос : Assign Message заполняет сообщение запроса, отправленное в удаленную службу.

• Ответ : Extract Variables анализирует ответ и извлекает определенное содержимое.

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

1. Назначить политику сообщений : создает сообщение запроса, заполняет заголовки HTTP, параметры запроса, устанавливает команду HTTP и т. д.
2. Политика вызова службы : ссылается на сообщение, созданное политикой назначения сообщения, определяет целевой URL-адрес для внешнего вызова и определяет имя объекта ответа, который возвращает целевая служба.
   
   Для повышения производительности вы также можете кэшировать ответы на вызовы службы, как описано в этой теме сообщества Apigee: https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the- servicecallout.html .
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>

Элемент <Запрос>

Указывает переменную, содержащую сообщение запроса, которое отправляется с прокси-сервера 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"/>

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

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

Элемент <HTPTTargetConnection>

Предоставляет сведения о транспорте, такие как 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>

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

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