Использование переменных потока

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

Концептуально, переменные потока — это объекты, к которым можно получить доступ из ваших политик или утилит (например, инструмента трассировки ). Они позволяют поддерживать состояние, связанное с транзакцией API, обрабатываемой Apigee Edge.

Что такое переменные потока?

Переменные потока существуют в контексте потока API-прокси и отслеживают состояние в транзакции API так же, как именованные переменные отслеживают состояние в программном обеспечении. Переменные потока хранят такую ​​информацию, как:

  • IP-адрес, заголовки, URL-адрес и полезная нагрузка, отправленные запрашивающим приложением.
  • Системная информация, такая как дата и время получения запроса Edge.
  • Данные, получаемые при выполнении политики. Например, после выполнения политики, проверяющей токен OAuth, Edge создает переменные потока, содержащие такую ​​информацию, как имя запрашивающего приложения.
  • Информация об ответе целевой системы.

Некоторые переменные "встроены" в Edge и автоматически заполняются при каждом получении запроса к API. Они доступны на протяжении всей транзакции API. Вы также можете создавать собственные пользовательские переменные, используя такие политики, как политика AssignMessage , или в коде JavaScript, Node.js и Java.

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

Как используются переменные потока?

Переменные потока используются в политиках и условных потоках :

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

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

  • Условные потоки могут ссылаться на переменные потока для управления потоком API через Edge, подобно тому, как работает оператор switch в программировании.

    Например, политика, возвращающая ошибку, может выполняться только тогда, когда установлена ​​определенная переменная потока. Наконец, вы можете получать и устанавливать переменные потока в целевом приложении Node.js.

Рассмотрим примеры использования переменных в каждом из этих контекстов.

Потоковые переменные в политике

Некоторые политики принимают в качестве входных данных переменные потока.

Например, следующая политика AssignMessage берет значение переменной потока client.ip и помещает его в заголовок запроса с именем My-Client-IP . Если она добавлена ​​к потоку запроса , эта политика устанавливает заголовок, который передается на целевую серверную часть. Если она установлена ​​в потоке ответа , заголовок отправляется обратно в клиентское приложение.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

В качестве другого примера, при выполнении политики квотирования несколько переменных потока заполняются значениями, связанными с политикой. Одна из этих переменных называется ratelimit.my-quota-policy.used.count (где my-quota-policy — это имя интересующей вас политики квотирования).

Позже вы можете выполнить условный поток, который гласит: «Если текущий уровень квоты ниже 50% от максимального значения и это время между 9:00 и 17:00, применить другую квоту». Это условие может зависеть от значения текущего уровня квоты и от переменной потока под названием system.time , которая является одной из встроенных переменных Edge.

Переменные потока в условных потоках

Условные потоки оценивают переменные потока и позволяют прокси-объектам вести себя динамически. Условия обычно используются для изменения поведения потоков, шагов и правил маршрутизации.

Вот пример условного потока, который оценивает значение переменной request.verb на этапе прокси-запроса. В данном случае, если глагол запроса — POST, выполняется политика VerifyAPIKey . Это распространенный шаблон, используемый в конфигурациях API-прокси.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

Возможно, вы задаетесь вопросом, откуда берутся такие переменные, как request.verb , client.ip и system.time ? Когда они создаются и заполняются значением? Чтобы помочь вам понять, когда создаются переменные и когда они становятся вам доступны, см. раздел «Понимание области видимости переменных потока» .

Переменные потока в коде JavaScript вызываются с использованием политики JavaScript.

С помощью политики JavaScript вы можете выполнять код JavaScript в контексте потока API-прокси. Выполняемый с помощью этой политики JavaScript использует объектную модель JavaScript Apigee, которая предоставляет вашему пользовательскому коду доступ к объектам запроса, ответа и контекста, связанным с потоком API-прокси, в котором выполняется ваш код. Например, этот код устанавливает заголовок ответа со значением, полученным из переменной потока target.name.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

Этот метод использования JavaScript для чтения и установки переменных аналогичен работе, которую можно выполнить с помощью политики AssignMessage (показанной ранее). Это просто еще один способ добиться того же самого в Edge. Важно помнить, что JavaScript, выполняемый политикой JavaScript, имеет доступ ко всем переменным потока, которые существуют и находятся в области видимости в рамках потока прокси-сервера API.

Переменные потока в коде Node.js

Подключив модуль apigee-access , вы можете устанавливать и получать доступ к переменным потока из кода Node.js, развернутого в Edge.

Вот простой пример, где переменной с именем custom.foo присваивается значение Bar . После установки эта новая переменная становится доступной для любых политик или другого кода, который выполняется в процессе прокси-сервера после выполнения кода Node.js.

var http = require('http');
var apigee = require('apigee-access');

http.createServer(function (request, response) {
  apigee.setVariable(request, "custom.foo", "Bar");
  response.writeHead(200, {'Content-Type': 'text/plain'});
  response.end('Hello World\n');
}).listen(8124);

console.log('Server running at http://127.0.0.1:8124/');

Подробнее об использовании apigee-access для работы с переменными можно прочитать в статье «Доступ к переменным потока в Node.js» .

Понимание области действия переменных потока

Область видимости переменных связана с потоком или общим «жизненным циклом» вызова API-прокси.

Визуализация потока работы API-прокси

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

На следующем рисунке показана эта последовательность потоков. Обратите внимание, что потоки состоят из четырех основных сегментов: запрос ProxyEndpoint, запрос TargetEndpoint, ответ TargetEndpoint и ответ ProxyEndpoint.

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

Как переменная область видимости связана с потоком прокси-сервера

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

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

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

Переменная область видимости Где эти переменные заполнены
прокси-запрос Сегмент запроса ProxyEndpoint
целевой запрос Сегмент запроса TargetEndpoint
целевой ответ Сегмент ответа TargetEnpoint
ответ через прокси Сегмент ответа ProxyEntpoint
всегда доступен Как только прокси-сервер получает запрос, эти переменные становятся доступны на протяжении всего жизненного цикла работы прокси-сервера.

Например, в Edge есть встроенная переменная client.ip . Эта переменная имеет область видимости "запрос к прокси". Она автоматически заполняется IP-адресом клиента, который вызвал прокси. Она заполняется при первом поступлении запроса в ProxyEndpoint и остается доступной на протяжении всего жизненного цикла потока прокси.

Существует ещё одна встроенная переменная под названием target.url . Область видимости этой переменной — "целевой запрос". Она заполняется в сегменте запроса TargetEndpoint URL-адресом запроса, отправляемым на целевой бэкэнд. Если вы попытаетесь получить доступ к target.url в сегменте запроса ProxyEndpoint, вы получите значение NULL. Если вы попытаетесь установить эту переменную до того, как она войдет в область видимости, прокси-сервер ничего не сделает — не сгенерирует ошибку и не установит переменную.

Вот простой пример, демонстрирующий, как следует понимать область видимости переменных. Предположим, вы хотите скопировать всё содержимое объекта запроса (заголовки, параметры, тело) и присвоить его полезной нагрузке ответа, отправляемого обратно вызывающему приложению. Для этой задачи можно использовать политику AssignMessage . Код политики выглядит следующим образом:

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

Эта политика просто копирует объект request и присваивает его объекту response . Но где именно в потоке прокси следует разместить эту политику? Ответ прост: её необходимо разместить в ответе TargetEndpoint, поскольку область действия переменной ответа — «ответ целевого объекта».

Ссылаясь на переменные потока

Все встроенные переменные в Apigee Edge используют точечную нотацию для именования. Это упрощает определение назначения переменной. Например, system.time.hour и request.content .

Apigee резервирует различные префиксы для надлежащей организации соответствующих переменных. К этим префиксам относятся:

  • request
  • response
  • system
  • target

Чтобы сослаться на переменную в политике, заключите её в фигурные скобки. Например, следующая политика AssignMessage берёт значение переменной client.ip и помещает его в заголовок запроса с именем Client-IP .

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

В условных потоках фигурные скобки не требуются. В следующем примере условия проверяется значение переменной request.header.accept :

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

Вы также можете ссылаться на переменные потока в коде JavaScript и Java. Для получения дополнительной информации см.:

Тип данных переменных потока

Каждое свойство переменной потока имеет четко определенный тип данных, например, String, Long, Integer, Boolean или Collection. Типы данных можно найти в справочнике по переменным потока . Для переменных, созданных политикой, обратитесь к соответствующему разделу справочника по политике для получения информации о типах данных.

Создаваемые вами вручную переменные принимают тип, указанный при их создании, и зависят от допустимых типов значений. Например, переменные, созданные в коде Node.js, могут принимать только значения Number, String, Boolean, null или undefined.

Использование переменных потока в политиках

Многие политики создают переменные потока в процессе своего обычного выполнения. В справочнике по политикам описаны все эти переменные, специфичные для каждой политики.

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

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

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

В следующем примере функция «Извлечение переменных» анализирует ответное сообщение и сохраняет определенные данные, взятые из ответа. Политика создает две пользовательские переменные, geocoderesponse.latitude и geocoderesponse.longitude , и присваивает им значения.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

Ещё раз напоминаем, что многие политики автоматически создают переменные. Вы можете получить доступ к этим переменным в контексте потока прокси, и они описаны в справочнике политик в разделе каждой отдельной политики.

Работа с переменными потока в коде JavaScript

Вы можете получать доступ к переменным и устанавливать их напрямую в коде JavaScript, выполняющемся в контексте API-прокси. Благодаря объектной модели JavaScript от Apigee, JavaScript, выполняющийся в Edge, имеет прямой доступ к переменным потока прокси.

Для доступа к переменным в коде JavaScript вызовите методы getter/setter для любого из этих объектов:

  • context
  • proxyRequest
  • proxyResponse
  • targetRequest
  • targetResponse

Как видите, эти ссылки на объекты соответствуют знакомым сегментам модели потока прокси-сервера, как объяснялось ранее в разделе «Визуализация потока API-прокси» .

Объект context соответствует «глобально» доступным переменным, таким как системные переменные. Например, вы можете вызвать getVariable() для объекта context , чтобы получить текущий год:

var year = context.getVariable('system.time.year');

Аналогично, вы можете вызвать setVariable() для установки значения пользовательской переменной или любой другой переменной, доступной для записи по умолчанию. Здесь мы создаём пользовательскую переменную с именем organization.name.myorg и присваиваем ей значение. 

var org = context.setVariable('organization.name.myorg', value);

Поскольку эта переменная создается вместе с объектом context , она будет доступна всем сегментам потока (по сути, это как создание глобальной переменной).

Вы также можете получать/устанавливать переменные прокси-потока в коде Java, который выполняется с помощью политики JavaCallout .

Доступ к переменным потока в приложениях Node.js

Вы можете получать, устанавливать и удалять переменные потока из кода Node.js, развернутого в Edge. Все, что вам нужно сделать, это подключить модуль apigee-access к вашему коду. Подробнее см. раздел « Доступ к переменным потока в Node.js» .

Что вам нужно помнить

Вот несколько важных моментов, которые следует помнить о переменных потока:

  • Некоторые «готовые» переменные создаются и заполняются автоматически самим прокси-объектом. Они описаны в справочнике по переменным потока .
  • Вы можете создавать пользовательские переменные, доступные для использования в процессе прокси-сервера. Создание переменных возможно с помощью таких политик, как политика AssignMessage и политика JavaScript , а также в коде Node.js.
  • Переменные имеют область видимости. Например, некоторые переменные автоматически заполняются, когда первый прокси-сервер получает запрос от приложения. Другие переменные заполняются в сегменте потока ответа прокси-сервера. Эти переменные ответа остаются неопределенными до тех пор, пока не будет выполнен сегмент ответа.
  • При выполнении политик могут создаваться и заполняться переменные, специфичные для каждой политики. В документации к каждой политике перечислены все эти соответствующие переменные.
  • Условные потоки обычно оценивают одну или несколько переменных. Для создания условных потоков необходимо понимать, что такое переменные.
  • Во многих политиках переменные используются в качестве входных или выходных данных. Например, переменная, созданная в рамках одной политики, впоследствии может быть использована в рамках другой.
  • Вы можете получать и устанавливать множество переменных потока непосредственно в Node.js, используя чистый JavaScript (и нашу объектную модель JavaScript ) или политику JavaCallout , которая выполняет код в Edge.

Примеры кода по теме

Примеры API-прокси размещены на GitHub и легко загружаются и используются. Информацию о загрузке и использовании примеров см. в разделе «Использование примеров API-прокси» . Описание примеров API-прокси и их функций см. в разделе «Список примеров» .

Примерами аппроксимаций, использующих переменные и обработку переменных, являются:

  • переменные — демонстрирует, как извлекать и устанавливать переменные на основе транспортного протокола, а также содержимого сообщений в форматах JSON и XML.
  • policy-mashup-cookbook — это полноценное приложение, использующее композицию политик для вызова двух общедоступных API, объединения результатов и генерации расширенного ответа для клиентского приложения. Дополнительную информацию об этом примере см. в разделе «Использование композиции политик» .
  • conditional-policy — Реализует простое условное применение политики на основе значений переменных.

Связанные темы

  • Все переменные, которые автоматически заполняются в API-прокси, перечислены в справочнике переменных Flow . В справочнике также указаны тип и область действия каждой переменной.
  • Если вы хотите узнать, какие переменные заполняет конкретная политика, обратитесь к справочному разделу по этой политике. Например, см. раздел «Переменные потока» в справочнике по политикам квот .