Справочник по настройке прокси-сервера API

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

Как разработчик, работающий с Apigee Edge, ваша основная задача — настройка API-прокси, которые функционируют как прокси для API или бэкэнд-сервисов. Этот документ является справочником по всем элементам конфигурации, доступным вам при создании API-прокси.

Если вы изучаете создание API-прокси, рекомендуется начать с темы «Создание простого API-прокси» .

Наиболее распространенные способы редактирования конфигураций прокси-сервера:

• Использование XML-редактора в пользовательском интерфейсе Edge
• Загрузите конфигурацию и отредактируйте ее локально, как описано в разделе «Локальная разработка конфигураций прокси» .

Локальная разработка конфигураций прокси-сервера

Вы можете загрузить свои конфигурации прокси-сервера, чтобы редактировать их на локальном компьютере. После завершения вы загружаете результаты в Edge. Такой подход позволяет интегрировать конфигурации прокси-сервера в вашу систему контроля версий, версионирования и другие общие рабочие процессы. Кроме того, работая над конфигурацией прокси-сервера локально, вы можете использовать собственный XML-редактор и инструменты проверки.

В этом разделе описывается, как с помощью пользовательского интерфейса загрузить существующую конфигурацию прокси-сервера, отредактировать ее, а затем загрузить обратно в Edge для развертывания. Вы также можете использовать apigeetool для загрузки и развертывания новой конфигурации прокси-сервера (с помощью команд fetchproxy и deployproxy соответственно).

Чтобы отредактировать конфигурацию прокси локально с помощью пользовательского интерфейса:

1. Загрузите текущую конфигурацию прокси-сервера в пользовательском интерфейсе Edge. (В разделе «Прокси API» выберите «Проект» > «Загрузить версию» .)
2. На локальном компьютере создайте новую директорию и распакуйте в неё загруженный ZIP-файл.

   Для распаковки ZIP-файла можно использовать такую ​​утилиту, как unzip , как показано в следующем примере:

   mkdir myappdir
   unzip ./my-app_app_rev3_2019_04_20.zip -d myappdir

   Расширенное содержимое ZIP-файла должно быть аналогично структуре, описанной в разделе «Структура прокси-сервера API» .

3. При необходимости отредактируйте исходные файлы. Описание исходных файлов в конфигурации прокси-сервера см. в разделе «Файлы конфигурации и структура каталогов API-прокси» .

   Например, чтобы включить мониторинг состояния вашего API-прокси, отредактируйте конфигурационный файл TargetEndpoint в каталоге /apiproxy/targets/ . Файл по умолчанию в этом каталоге называется default.xml , хотя при использовании условных целей могут быть файлы с другими именами.

   В этом случае, если файл конфигурации TargetEndpoint и соответствующая директория отсутствуют, создайте их.

4. После завершения редактирования файлов конфигурации прокси-сервера обязательно сохраните изменения.
5. Перейдите в новую директорию, которую вы создали при распаковке ZIP-файлов (корневая директория распакованных конфигурационных файлов).

   Например, если вы распаковали файлы в каталог /myappdir , перейдите в этот каталог, как показано в следующем примере:

   cd myappdir

   Перед повторным архивированием файлов конфигурации прокси-сервера вам следует перейти в этот каталог, поскольку каталог /myappdir не должен быть включен в ZIP-архив. В ZIP-архиве корневым каталогом должен быть /apiproxy .

6. Заархивируйте файлы конфигурации прокси-сервера, включая новые или измененные файлы. Для этого можно использовать такую ​​утилиту, как zip , как показано в следующем примере:

   zip my-new-proxy.zip -r .

   В корневом каталоге ZIP-файла должен быть /apiproxy .

   К имени ZIP-файла нет особых требований. Например, не нужно увеличивать номер ревизии или указывать дату в имени файла, но это может быть полезно для отладки или контроля версий.

   Edge автоматически увеличивает номер версии новой конфигурации прокси-сервера при ее загрузке.

7. Загрузите новую конфигурацию прокси-сервера с помощью пользовательского интерфейса Edge. (В разделе «Прокси API» выберите «Проект» > «Загрузить новую версию» .)

   Если вы получили ошибку типа Bundle is invalid. Empty bundle. , убедитесь, что корневой каталог вашего ZIP-файла — /apiproxy . Если это не так, повторно заархивируйте файлы конфигурации прокси из корневого каталога, в который вы его распаковали.

   После загрузки новой конфигурации прокси-сервера Edge увеличивает номер версии и отображает его в разделе «Сводка версий» .

   После загрузки новой версии через пользовательский интерфейс Edge не устанавливает её автоматически.

8. Разверните новую версию.

Для получения более подробной информации см. руководство: Как загрузить прокси-сервер с помощью пользовательского интерфейса и API управления в сообществе Apigee .

структура API-прокси

API-прокси состоит из следующей конфигурации:

Структура и содержимое каталога API-прокси

Компоненты, указанные в таблице выше, определяются конфигурационными файлами, расположенными в следующей структуре каталогов:

Конфигурационные файлы и структура каталогов API-прокси

В этом разделе описываются конфигурационные файлы и структура каталогов API-прокси.

• Базовая конфигурация
• ProxyEndpoint
• Целевая точка
  • Конфигурация целевой/конечной точки TLS/SSL
• Политики
• Потоки
• Ресурсы

Базовая конфигурация

/apiproxy/weatherapi.xml

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

Пример конфигурации:

<APIProxy name="weatherapi">
</APIProxy>

Элементы базовой конфигурации

ProxyEndpoint

На следующем изображении показана последовательность запросов и ответов:

/apiproxy/proxies/default.xml

Конфигурация ProxyEndpoint определяет входящий (обращенный к клиенту) интерфейс для прокси-сервера API. При настройке ProxyEndpoint вы задаете сетевую конфигурацию, которая определяет, как клиентские приложения («apps») должны вызывать проксируемый API.

Пример конфигурации ProxyEndpoint, приведенный ниже, будет храниться в каталоге /apiproxy/proxies :

<ProxyEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPProxyConnection>
    <BasePath>/weather</BasePath>
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

В базовой конфигурации ProxyEntpoint необходимы следующие элементы:

Элементы конфигурации ProxyEndpoint

Как настроить правила маршрутизации (RouteRules)

Именованный TargetEndpoint — это конфигурационный файл, расположенный в каталоге /apiproxy/targets , на который RouteRule перенаправляет запрос после обработки ProxyEndpoint.

Например, следующее правило маршрутизации (RouteRule) ссылается на конфигурационный файл /apiproxy/targets/myTarget.xml :

<RouteRule name="default">
  <TargetEndpoint>myTarget</TargetEndpoint>
</RouteRule>

Прямой вызов URL

ProxyEndpoint также может напрямую вызывать бэкэнд-сервис. Прямой вызов по URL-адресу обходит любую конфигурацию именованных TargetEndpoints в каталоге /apiproxy/targets . По этой причине TargetEndpoint является необязательной конфигурацией API-прокси, хотя на практике прямой вызов из ProxyEndpoint не рекомендуется.

Например, следующее правило маршрутизации (RouteRule) выполняет HTTP-запрос к адресу http://api.mycompany.com/v2 .

<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

Условные маршруты

Правила маршрутизации можно объединять в цепочки для поддержки динамической маршрутизации во время выполнения. Входящие запросы могут направляться к именованным конфигурациям TargetEndpoint, непосредственно к URL-адресам или к их комбинации в зависимости от HTTP-заголовков, содержимого сообщения, параметров запроса или контекстной информации, такой как время суток, локаль и т. д.

Условные правила маршрутизации работают аналогично другим условным операторам в Apigee Edge. См. справочник по условиям и справочник по переменным .

Например, следующая комбинация RouteRule сначала проверяет входящий запрос, чтобы убедиться в значении HTTP-заголовка. Если HTTP-заголовок routeTo имеет значение TargetEndpoint1 , то запрос перенаправляется на целевой объект TargetEndpoint1 . В противном случае входящий запрос перенаправляется на http://api.mycompany.com/v2 .

<RouteRule name="MyRoute">
  <Condition>request.header.routeTo = "TargetEndpoint1"</Condition>
  <TargetEndpoint>TargetEndpoint1</TargetEndpoint>
</RouteRule>
<RouteRule name="default">
  <URL>http://api.mycompany.com/v2</URL>
</RouteRule>

Пустые маршруты

Для поддержки сценариев, в которых сообщение запроса не нужно перенаправлять в TargetEndpoint, можно определить RouteRule со значением null. Это полезно, когда ProxyEndpoint выполняет всю необходимую обработку, например, используя JavaScript для вызова внешней службы или извлекая данные из таблицы поиска в хранилище ключ/значение API-сервисов.

Например, ниже определен маршрут со значением null:

<RouteRule name="GoNowhere"/>

Условные маршруты со значением null могут быть полезны. В следующем примере маршрут со значением null настроен на выполнение, когда заголовок HTTP request.header.X-DoNothing имеет значение, отличное от null .

<RouteRule name="DoNothingOnDemand">
  <Condition>request.header.X-DoNothing != null</Condition>
</RouteRule>

Помните, что правила маршрутизации (RouteRules) можно объединять в цепочки, поэтому условный маршрут со значением null обычно является одним из компонентов набора правил маршрутизации, предназначенных для поддержки условной маршрутизации.

Практическое применение условного маршрута со значением null — поддержка кэширования. Используя значение переменной, установленной политикой кэширования, можно настроить API-прокси для выполнения маршрута со значением null при получении записи из кэша.

<RouteRule name="DoNothingUnlessTheCacheIsStale">
  <Condition>lookupcache.LookupCache-1.cachehit is true</Condition>
</RouteRule>

Целевая точка

TargetEndpoint — это исходящий аналог ProxyEndpoint. TargetEndpoint функционирует как клиент для бэкэнд-сервиса или API — он отправляет запросы и получает ответы.

API-прокси не обязательно должен иметь TargetEndpoints. ProxyEndpoints можно настроить для прямого вызова URL-адресов. API-прокси без TargetEndpoints обычно содержит ProxyEndpoint, который либо напрямую вызывает бэкэнд-сервис, либо настроен на вызов сервиса с использованием Java или JavaScript.

Конфигурация целевой конечной точки

/targets/default.xml

Параметр TargetEndpoint определяет исходящее соединение от Apigee Edge к другой службе или ресурсу.

Вот пример конфигурации TargetEndpoint:

<TargetEndpoint name="default">
  <PreFlow/>
  <Flows/>
  <PostFlow/>
  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
    <SSLInfo/>
  </HTTPTargetConnection>
  <FaultRules/>
  <DefaultFaultRule/>
  <ScriptTarget/>
  <LocalTargetConnection/>
</TargetEndpoint>

Элементы конфигурации TargetEndpoint

Объект TargetEndpoint может вызывать целевой объект одним из следующих способов:

• HTTPTargetConnection для HTTP(S) вызовов
• LocalTargetConnection для цепочки локальных прокси-серверов.
• ScriptTarget для вызовов скрипта Node.js , размещенного на сервере Edge.

В TargetEndpoint следует настроить только один из этих параметров.

Конфигурация целевой/конечной точки TLS/SSL

Целевым конечным точкам часто приходится управлять HTTPS-соединениями с гетерогенной серверной инфраструктурой. По этой причине поддерживается ряд параметров конфигурации TLS/SSL.

Элементы конфигурации целевой конечной точки TLS/SSL

<Ciphers>
 <Cipher>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Cipher>
 <Cipher>TLS_RSA_WITH_DES_CBC_SHA</Cipher>
</Ciphers>

<Protocols>
 <Protocol>TLSv1.1</Protocol>
 <Protocol>TLSv1.2</Protocol>
</Protocols>

<CommonName wildcardMatch="true">*.myhost.com</CommonName>

Пример целевой конечной точки с включенной исходящей аутентификацией клиента.

<TargetEndpoint name="default">
  <HttpTargetConnection>
        <URL>https://myservice.com</URL>
    <SSLInfo>
      <Enabled>true</Enabled>
      <ClientAuthEnabled>true</ClientAuthEnabled>
      <KeyStore>myKeystore</KeyStore>
      <KeyAlias>myKey</KeyAlias>
      <TrustStore>myTruststore</TrustStore>
    </SSLInfo>
  </HttpTargetConnection>
</TargetEndpoint>

Подробные инструкции см. в разделе «Настройка TLS от периферии сети к серверной части (облако и частное облако)» .

Использование переменных потока для динамической установки значений TLS/SSL.

Вы также можете динамически устанавливать параметры TLS/SSL для поддержки гибких требований среды выполнения. Например, если ваш прокси-сервер подключается к двум потенциально разным целевым объектам (тестовому и производственному), вы можете настроить API-прокси таким образом, чтобы он программно определял, к какой среде он обращается, и динамически устанавливал ссылки на соответствующее хранилище ключей и хранилище доверенных сертификатов. В следующей статье сообщества Apigee этот сценарий объясняется более подробно и приводятся примеры развертывания API-прокси: Динамическая SSLInfo для TargetEndpoint с использованием ссылки на переменную .

В следующем примере установки тега <SSLInfo> в конфигурации TargetEndpoint значения могут быть предоставлены во время выполнения, например, с помощью вызова Java, политики JavaScript или политики назначения сообщений. Используйте те переменные сообщения, которые содержат значения, которые вы хотите установить.

Переменные допускаются только в следующих элементах.

<SSLInfo>
    <Enabled>{myvars.ssl.enabled}</Enabled>
    <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
    <KeyStore>{myvars.ssl.keystore}</KeyStore>
    <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
    <TrustStore>{myvars.ssl.trustStore}</TrustStore>
</SSLInfo>

Использование ссылок для динамической установки значений TLS/SSL.

При настройке целевой конечной точки, использующей HTTPS, необходимо учитывать случай истечения срока действия сертификата TLS/SSL или необходимости обновления сертификата в связи с изменением конфигурации системы. В установке Edge for Private Cloud при настройке TLS/SSL с использованием статических значений или переменных потока существует вероятность необходимости перезапуска обработчиков сообщений.

Дополнительную информацию см. в разделе «Обновление TLS-сертификата» .

Однако, при желании, вы можете настроить TargetEndpoint так, чтобы он использовал ссылку на хранилище ключей или доверенных сертификатов. Преимущество использования ссылки заключается в том, что вы можете обновить ссылку, указав на другое хранилище ключей или доверенных сертификатов, чтобы обновить сертификат TLS/SSL без необходимости перезапуска обработчиков сообщений.

Например, ниже показана целевая конечная точка (TargetEndpoint), использующая ссылку на хранилище ключей:

<SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>false</ClientAuthEnabled>
    <KeyStore>ref://keystoreref</KeyStore>
    <KeyAlias>myKeyAlias</KeyAlias>
</SSLInfo>

Для создания ссылки с именем keystoreref используйте следующий POST-запрос к API:

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
-d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

В ссылке указывается имя хранилища ключей и его тип.

Для просмотра справочной информации воспользуйтесь следующим вызовом API GET:

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

Чтобы впоследствии изменить ссылку и указать на другое хранилище ключей, убедившись, что псевдоним имеет то же имя, используйте следующий вызов PUT:

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
-d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
</ResourceReference>' -u email:password

TargetEndpoint с балансировкой нагрузки на целевой объект.

TargetEndpoints поддерживают балансировку нагрузки между несколькими именованными TargetServers с использованием трех алгоритмов балансировки нагрузки.

Подробные инструкции см. в разделе « Балансировка нагрузки между серверами бэкэнда» .

Политики

В каталоге /policies в API-прокси содержатся все политики, которые можно прикрепить к потокам в API-прокси.

Элементы конфигурации политики

Приложение к полису

На следующем изображении показана последовательность выполнения потоков API-прокси:

Как показано выше:

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

<Step><Name>MyPolicy</Name></Step>

Политики применяются в том порядке, в котором они привязаны к потоку. Например:

<Step><Name>FirstPolicy</Name></Step>
<Step><Name>SecondPolicy</Name></Step>

Элементы конфигурации прикрепления политики

Потоки

ProxyEndpoint и TargetEndpoint определяют конвейер обработки запросов и ответов. Конвейер обработки состоит из потока запроса и потока ответа. Каждый поток запроса и поток ответа подразделяются на PreFlow, один или несколько необязательных «условных» или «именованных» потоков и PostFlow.

• PreFlow: Всегда выполняется. Выполняется перед любыми условными потоками.
• PostFlow: Всегда выполняется. Выполняется после любых условных потоков.

Кроме того, вы можете добавить PostClientFlow к ProxyEndpoint, который выполняется после того, как ответ будет возвращен запрашивающему клиентскому приложению. К этому потоку можно прикрепить только политику MessageLogging и расширение Google Stackdriver Logging Extension . PostClientFlow уменьшает задержку API-прокси и предоставляет для логирования информацию, которая вычисляется только после того, как ответ будет возвращен клиенту, например, client.sent.start.timestamp и client.sent.end.timestamp . Этот поток используется в основном для измерения временного интервала между метками начала и конца ответного сообщения.

Посмотрите короткое видео с инструкцией.

Вот пример PostClientFlow с прикрепленной политикой логирования сообщений.

    ...
    <PostFlow name="PostFlow">
        <Request/>
        <Response/>
    </PostFlow>
    <PostClientFlow>
        <Request/>
        <Response>
            <Step>
                <Name>Message-Logging-1</Name>
            </Step>
        </Response>
    </PostClientFlow>
    ...

Конвейер обработки API-прокси выполняет потоки в следующей последовательности:

Конвейер обработки запросов:

1. Предварительный поток запроса прокси
2. Условные потоки запросов через прокси (необязательно)
3. Постпоток запроса прокси
4. Предварительный поток целевого запроса
5. Условные потоки целевого запроса (необязательно)
6. Постпоток целевого запроса

Конвейер обработки ответов:

1. Предварительный поток ответа на целевой запрос
2. Target Response Conditional Flows (Optional)
3. Target Response PostFlow
4. Proxy Response PreFlow
5. Proxy Response Conditional Flows (Optional)
6. Proxy Response PostFlow
7. PostClientFlow Response (Optional)

Only those Flows with policy attachments need to be configured in ProxyEndpoint or TargetEndpoint configurations. PreFlow and PostFlow need only be specified in a ProxyEndpoint or TargetEndpoint configuration when a policy needs to be enforced during PreFlow or PostFlow processing.

In contrast to conditional flows, the ordering of PreFlow and PostFlow elements is not important--the API proxy will always execute each at the appropriate point in the pipeline, regardless of where they appear in the Endpoint configuration.

Conditional Flows

ProxyEndpoints and TargetEndpoints support an unlimited number of conditional flows (also known as 'named flows').

The API proxy tests for the condition specified in the conditional flow and, if the condition is met, the processing steps in the conditional flow are executed by the API proxy. If the condition is not met, then the processing steps in the conditional flow are bypassed. Conditional flows are evaluated in the order defined in the API proxy and the first one whose condition is met is executed.

By defining conditional flows, you gain the ability to apply processing steps in an API proxy based on:

• Request URI
• HTTP verb (GET/PUT/POST/DELETE)
• Value of a query param, header, and form param
• Many other types of conditions

For example, the following conditional flow specifies that it is executed only when the request resource path is /accesstoken . Any inbound request with the path /accesstoken causes this flow to be executed, along with any policies that are attached to the flow. If the request path does not include the suffix /accesstoken , then the flow does not execute (although another conditional flow might).

<Flows>
  <Flow name="TokenEndpoint">
    <Condition>proxy.pathsuffix MatchesPath "/accesstoken"</Condition>
    <Request>
      <Step>
        <Name>GenerateAccessToken</Name>
      </Step>
    </Request>
  </Flow>
</Flows>

Flow Configuration Elements

Step processing

The sequential ordering of conditional Flows is enforced by Apigee Edge. Conditional Flows execute from top to bottom. The first conditional Flow whose condition evaluates to true is executed, and only one conditional Flow is executed.

For example, in the following Flow configuration, any inbound request that does not include the path suffix /first or /second will cause the ThirdFlow to execute, enforcing the policy called Return404 .

<Flows>
  <Flow name="FirstFlow">
    <Condition>proxy.pathsuffix MatchesPath "/first"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="SecondFlow">
    <Condition>proxy.pathsuffix MatchesPath "/second"</Condition>
    <Request>
      <Step><Name>FirstPolicy</Name></Step>
      <Step><Name>SecondPolicy</Name></Step>
    </Request>
  </Flow>
  <Flow name="ThirdFlow">
    <Request>
      <Step><Name>Return404</Name></Step>
    </Request>
  </Flow>
</Flows>

Ресурсы

"Resources" (resource files for use in API proxies) are scripts, code, and XSL transformations that can be attached to Flows using policies. These appear in the "Scripts" section of the API proxy editor in the management UI.

See Resource files for the supported resource types.

Resources can be stored in an API proxy, an environment, or an organization. In each case, a resource is referenced by name in a Policy. API Services resolves the name by moving from the API proxy, to environment, to organization level.

A resource stored at the organization level can be referenced by Policies in any environment. A resource stored at the environment level can be referenced by Policies in that environment. A resource stored at the API proxy level can be referenced only by Policies in that API proxy.