Справочник по конфигурации прокси-сервера API

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

Основная задача разработчика, работающего с Apigee Edge, – настраивать прокси API, которые выступают в качестве прокси для API или серверных сервисов. В этом документе перечислены все элементы конфигурации, доступные при создании прокси API.

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

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

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

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

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

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

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

1. Скачайте текущую конфигурацию прокси-сервера в интерфейсе Edge. (В представлении API Proxies (Прокси API) выберите Project > Download Revision (Проект > Скачать версию).)
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 Proxies (Прокси API) выберите Project > Upload a New Revision (Проект > Загрузить новую версию).)

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

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

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

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

Подробнее о том, как скачать прокси-сервер с помощью интерфейса и Management API… (статья на форуме Apigee).

Структура прокси-сервера API

Прокси-сервер API состоит из следующих компонентов:

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

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

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

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

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

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

/apiproxy/weatherapi.xml

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

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

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

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

ProxyEndpoint

На изображении ниже показан поток запросов и ответов.

/apiproxy/proxies/default.xml

Конфигурация ProxyEndpoint определяет входящий (клиентский) интерфейс для прокси API. Когда вы настраиваете ProxyEndpoint, вы задаете конфигурацию сети, которая определяет, как клиентские приложения должны вызывать 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>

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

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

Как настроить RouteRules

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

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

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

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

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

Например, следующее правило маршрутизации выполняет вызов 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, запрос пересылается в TargetEndpoint с именем 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>

Нулевые маршруты

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

Например, следующий код определяет нулевой маршрут:

<RouteRule name="GoNowhere"/>

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

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

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

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

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

TargetEndpoint

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

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

Конфигурация TargetEndpoint

/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 можно настроить только один из этих элементов.

Конфигурация TargetEndpoint для TLS/SSL

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

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

<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 с включенной исходящей аутентификацией клиента

<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 от Edge до внутреннего сервера (в облаке и частном облаке).

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

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

В следующем примере показано, как задать тег <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

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

Подробнее о том, как обновить сертификат TLS…

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

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

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

Чтобы создать ссылку с именем keystoreref, используйте следующий вызов API POST:

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 поддерживает балансировку нагрузки между несколькими именованными TargetServer с помощью трех алгоритмов балансировки нагрузки.

Подробные инструкции приведены в статье Как настроить балансировку нагрузки между внутренними серверами.

Правила

Каталог /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: выполняется всегда. Выполняется после всех условных потоков.

Кроме того, вы можете добавить в ProxyEndpoint поток PostClientFlow, который выполняется после того, как ответ возвращается в клиентское приложение, отправившее запрос. К этому потоку можно прикрепить только правило MessageLogging и расширение Google Stackdriver Logging. 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. Proxy Request PreFlow
2. Процессы с условиями для запросов прокси-сервера (необязательно)
3. Proxy Request PostFlow
4. Target Request PreFlow
5. Целевые условные потоки запросов (необязательно)
6. Target Request PostFlow

Конвейер ответов:

1. Target Response PreFlow
2. Целевые процессы с условиями для ответов (необязательно)
3. Целевой ответ PostFlow
4. Proxy Response PreFlow
5. Условные процессы ответа прокси-сервера (необязательно)
6. Proxy Response PostFlow
7. Ответ PostClientFlow (необязательно)

В конфигурациях ProxyEndpoint или TargetEndpoint необходимо настроить только те потоки, к которым прикреплены правила. PreFlow и PostFlow нужно указывать в конфигурации ProxyEndpoint или TargetEndpoint только в том случае, если правило должно применяться во время обработки PreFlow или PostFlow.

В отличие от условных потоков, порядок элементов PreFlow и PostFlow не имеет значения – прокси-сервер API всегда будет выполнять каждый из них в нужный момент конвейера, независимо от того, где они указаны в конфигурации конечной точки.

Процессы с условиями

ProxyEndpoint и TargetEndpoint поддерживают неограниченное количество условных потоков (также известных как именованные потоки).

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

Определив условные потоки, вы сможете применять шаги обработки в прокси-сервере API на основе:

• URI запроса
• Глагол HTTP (GET, PUT, POST, DELETE)
• Значение параметра запроса, заголовка и параметра формы
• другие типы условий.

Например, в условном потоке ниже указано, что он выполняется только в том случае, если путь к ресурсу запроса – /accesstoken. Любой входящий запрос с путем /accesstoken приводит к выполнению этого процесса, а также любых правил, прикрепленных к нему. Если путь запроса не включает суффикс /accesstoken, поток не выполняется (хотя может выполниться другой условный поток).

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

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

Обработка шагов

Последовательность условных потоков обеспечивается Apigee Edge. Условные потоки выполняются сверху вниз. Выполняется первый условный процесс, условие которого оценивается как true. Выполняется только один условный процесс.

Например, в приведенной ниже конфигурации потока любой входящий запрос, который не включает суффикс пути /first или /second, приведет к выполнению ThirdFlow, обеспечивая соблюдение правила 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>

Ресурсы

Ресурсы (файлы ресурсов для использования в прокси API) – это скрипты, код и преобразования XSL, которые можно прикрепить к потокам с помощью правил. Они будут показаны в разделе "Скрипты" редактора прокси API в интерфейсе управления.

Поддерживаемые типы ресурсов перечислены в разделе Файлы ресурсов.

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

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