Управление работой прокси с потоками

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

Любая модель прикладного программирования включает способ управления потоком обработки. В прокси API это делается с помощью потоков. К потокам вы добавляете логику, операторы условий, обработку ошибок и так далее. Вы используете потоки, чтобы контролировать, что происходит и когда.

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

В следующем примере конфигурации потока определяется поток, в котором выполняется политика VerifyAPIKey, если путь входящего запроса заканчивается знаком / и HTTP-командой запроса является GET.

<Flow name="Get Food Carts">
    <Description>Get Food Carts</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Значение Verify-API-Key в элементе <Name> потока служит для включения политики, настроенной в другом месте прокси-сервера с помощью XML, например:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <Properties/>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

Разработка последовательности выполнения потока

Вы структурируете потоки так, чтобы логика выполнялась в правильной последовательности на пути обработки.

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

Обе конечные точки содержат потоки, как описано здесь:

Тип конечной точки Описание Поддерживаемые потоки
Конечная точка прокси Содержит потоки прокси-сервера API, ближайшие к клиенту. Предоставляет места для логики, которая сначала действует на запрос от клиента, а затем на ответ клиенту. PreFlow, условные потоки, PostFlow, PostClientFlow
Целевая конечная точка Содержит потоки прокси-сервера API, ближайшие к внутреннему ресурсу. Предоставляет места для логики для подготовки запроса, а затем обработки ответа от внутреннего ресурса. PreFlow, условные потоки, PostFlow

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

Запрос от HTTP-клиента, проходящий через конечную точку прокси к целевой конечной точке на серверной части, для доступа к службе HTTP. Каждая панель запросов и ответов показывает предварительный поток, условные потоки и постпроцесс. Кроме того, приведены примеры конечной точки прокси и целевой конечной точки.

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

Позиция Тип потока Описание
1 Предпоток

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

Если PreFlow находится в целевой конечной точке, он выполняется после PostFlow конечной точки прокси.

2 Условный поток

Место для условной логики. Выполняется после PreFlow и перед PostFlow.

Для каждого сегмента выполняется только один условный поток — первый поток, условие которого оценивается как истинное. Это означает, что вы можете выполнить один условный поток как часть каждого из:
  • Конвейер запросов ProxyEndpoint
  • Конвейер запросов TargetEndpoint
  • Конвейер ответов ProxyEndpoint
  • Конвейер ответов TargetEndpoint
3 постфлоу

Хорошее место для регистрации данных, отправки уведомления о том, что что-то произошло при обработке запроса и т.д. Выполняется после условных потоков и PreFlow.

Если PostFlow находится в конечной точке прокси и есть целевая конечная точка, PostFlow конечной точки прокси выполняется до PreFlow целевой конечной точки.

4 PostClientFlow (только прокси-поток) Поток для регистрации сообщений после того, как ответ возвращен клиенту.

Выполнение кода первым с помощью PreFlow

PreFlow полезен, когда вам нужно убедиться, что определенный код выполняется до того, как произойдет что-либо еще.

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

Например, обычно вы не хотите обслуживать клиента, который превысил свою квоту. Для поддержки этих требований вы помещаете политики безопасности и квот в сегмент PreFlow. Таким образом, вам не нужно беспокоиться о том, что условие не может быть оценено в более позднем условном потоке. Политики в этом потоке всегда будут выполняться до выполнения любой другой обработки.

В следующем примере политики SpikeArrest и Quota выполняются перед передачей обработки условным потокам.

<PreFlow name="MyPreFlow">
    <Request>
        <Step>
            <Name>Spike-Arrest</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
</PreFlow>

Условное выполнение кода с условным потоком

Между PreFlow и PostFlow у вас могут быть потоки, которые выполняются условно. Это дает вам возможность настроить несколько последовательностей логики, но выполнять только одну в зависимости от состояния вашего прокси. Условный поток является необязательным, если вы можете выполнить всю логику в PreFlow или PostFlow и не требуются никакие условия (другими словами, поддерживается только один путь через конечную точку).

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

Здесь ограничения квоты применяются только в том случае, если запрос является запросом GET с шаблоном URI /issue/** (/issue/ с чем-либо в URI после последней косой черты).

<Flow name="MyFlow">
    <Description/>
    <Request>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>

Вы используете переменные потока для указания условий. Дополнительные сведения об использовании переменных в условиях см. в разделе Условия с переменными потока .

Примеры использования сопоставления шаблонов в условиях см. в разделе Сопоставление шаблонов .

Выполнение кода после базовой логики с помощью PostFlow

PostFlow — это отличное место для выполнения действий после основной логики вашей конечной точки и до завершения обработки конечной точки. PostFlow выполняется после условных потоков и PreFlow.

PostFlow — это хорошее место для регистрации некоторых данных, отправки уведомления о том, что что-то произошло, преобразования формата ответного сообщения и т. д.

В следующем примере политика AssignMessage с именем SetResponseHeaders устанавливает заголовки ответного сообщения до того, как Apigee Edge отправит ответ обратно клиенту.

<PostFlow>
    <Response>
        <Step>
            <Name>SetResponseHeaders</Name>
        </Step>
    </Response>
 </PostFlow>

Выполнение кода после того, как клиент получит ответ вашего прокси с помощью PostClientFlow

PostClientFlow может включать следующие политики:

* Политика FlowCallout может вызывать только общие потоки, которые сами соответствуют критериям для включения в PostClientFlow (т. е. содержат только совместимые политики).

Если вы включите его, PostClientFlow будет последним выполняемым потоком, выполняющимся после отправки ответа клиенту.

PostClientFlow хорош для окончательной регистрации. Кроме того, вы можете регистрировать метки времени начала и окончания ответного сообщения.

Вот пример PostClientFlow с прикрепленной политикой MessageLogging.

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

Видео. Посмотрите это короткое видео, в котором показано, как создать PostClientFlow с помощью политики MessageLogging из серии «Четырехминутное видео для разработчиков» (4MV4D).

Для получения дополнительной информации см.:

Добавление логики в потоки

Когда вы добавляете логику к своему прокси, вы делаете это, добавляя политики к потокам вашего прокси. Подобно тому, как потоки выполняются в последовательности (PreFlow, затем Flow, а затем PostFlow, как описано в этом разделе), содержимое потока выполняется в последовательности.

Конфигурация потока в следующем примере ссылается на три политики (настроенные в другом месте в своих собственных XML-файлах). Политика, на которую ссылается Verify-API-Key выполняется до политики, на которую ссылается Remove-API-Key ; за обоими следует политика, представленная Quota .

<Flow name="Get Food Cart Menus">
    <Description>Get Food Cart Menus</Description>
    <Request>
        <Step>
            <Name>Verify-API-Key</Name>
        </Step>
        <Step>
            <Name>Remove-API-Key</Name>
        </Step>
        <Step>
            <Name>Quota</Name>
        </Step>
    </Request>
    <Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>

Консоль Apigee Edge представляет эту последовательность политик в виде ряда значков, где каждый значок представляет политику.

Консоль Apigee Edge представляет эту последовательность политик в виде ряда значков, где каждый значок представляет политику. Значки, отображаемые на пути запроса, включают в себя: Проверить ключ API, Удалить ключ API и Квоту.

Отладка потоков

Инструмент Apigee Edge Trace предоставляет графический способ увидеть, как логика в вашем API-прокси выполняется после запроса. Инструмент иллюстрирует обработку между запросом и ответом. Он конкретно не иллюстрирует разделение между PreFlow, условными потоками и PostFlow.

Дополнительные сведения о трассировке прокси-серверов см. в разделе Использование инструмента трассировки .

Обработка ошибок в потоках

Вы можете вызывать ошибки из разных мест прокси-сервера API, в том числе из потоков.

В следующем примере показана строфа ответа от PreFlow в целевой конечной точке, другими словами, это код, который выполняется сразу после получения ответа от целевой серверной части. В примере возникает ошибка, если ответ от цели не равен 200 (успех).

<PreFlow name="PreFlow">
    <Response>
        <Step>
            <Name>RaiseFault</Name>
            <Condition>(response.status.code GreaterThan "200")</Condition>
        </Step>
    </Response>
</PreFlow>

Дополнительные сведения об обработке ошибок см. в разделе Обработка ошибок .