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

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

Как разработчик, работающий с 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.

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

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

/apiproxy/weatherapi.xml

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

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

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

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

ПроксиКонечная точка

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

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

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

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

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

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

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

TargetEndpoints часто требуется управлять 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 программно определять, какую среду он вызывает, и динамически устанавливать ссылки на соответствующее хранилище ключей и хранилище доверенных сертификатов. В следующей статье сообщества Apigee этот сценарий объясняется более подробно и приводятся примеры развертываемых прокси-серверов API: https://community.apigee.com/articles/21424/dynamic-sslinfo-for-targetendpoint-using-variable.html .

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

Используйте следующий вызов 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

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

Чтобы просмотреть ссылку, используйте следующий вызов GET API:

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:

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

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

<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 . 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. Постфлоу целевого запроса

Канал ответа:

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

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

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

Условные потоки

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

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

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

• Запрос URI
• Http глагол (get/pot/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.