Справочник по настройке прокси-сервера 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
• 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.

Например, следующее правило 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>

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

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

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

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

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

<RouteRule name="GoNowhere"/>

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

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

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

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

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

TargetEndpoint

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

<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-прокси на программную фиксацию вызываемой среды и динамическую установку ссылок на соответствующие хранилища ключей и доверенных сертификатов. В следующей статье сообщества Apigee этот сценарий подробно описан и приведены примеры развёртываемых API-прокси: Dynamic SSLInfo for TargetEndpoint using variable reference .

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

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

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. PreFlow запроса прокси
2. Условные потоки запросов прокси (необязательно)
3. Запрос прокси PostFlow
4. Целевой запрос PreFlow
5. Условные потоки целевого запроса (необязательно)
6. Целевой запрос PostFlow

Конвейер реагирования:

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

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

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:

• Запрос 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.