Вы просматриваете документацию по Apigee Edge.
См. документацию по Apigee X.
Концептуально переменные потока — это объекты, к которым вы можете получить доступ из своих политик или утилит (таких как инструмент Trace ). Они позволяют вам поддерживать состояние, связанное с транзакцией 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, который выполняется с помощью этой политики, использует объектную модель Apigee JavaScript , которая предоставляет вашему пользовательскому коду доступ к объектам запроса, ответа и контекста, связанным с потоком прокси 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 |
целевой ответ | Сегмент ответа TargetEndpoint |
ответ прокси | Сегмент ответа ProxyEndpoint |
всегда доступен | Как только прокси получает запрос. Эти переменные доступны на протяжении всего жизненного цикла прокси-потока. |
Например, есть встроенная переменная 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, могут быть числовыми, строковыми, логическими, нулевыми или неопределенными.
Использование переменных потока в политиках
Многие политики создают переменные потока как часть их обычного выполнения. Справочник по политике документирует все эти переменные, относящиеся к политике.
При работе с прокси и политиками обязательно обращайтесь к справочнику по политике, чтобы узнать, какие переменные создаются и для чего они используются. Например, политика Quota создает набор переменных, содержащих информацию о количестве и ограничениях квоты, времени истечения срока действия и т. д.
Некоторые переменные политики полезны для отладки. Вы можете использовать инструмент Trace , например, чтобы увидеть, какие переменные были установлены в конкретном экземпляре прокси-потока.
Политика 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, вызовите методы получения/установки для любого из этих объектов:
-
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. Все, что вам нужно сделать, это «требовать» модуль доступа к API в вашем коде. Подробнее см. в разделе Доступ к переменным потока в Node.js.
Что вам нужно помнить
Вот несколько важных вещей, которые следует помнить о переменных потока:
- Некоторые «стандартные» переменные создаются и заполняются автоматически самим прокси. Они описаны в справочнике по переменным потока .
- Вы можете создавать настраиваемые переменные, доступные для использования в потоке прокси. Переменные можно создавать с помощью таких политик, как политика AssignMessage и политика JavaScript , а также в коде Node.js.
- Переменные имеют область видимости. Например, некоторые переменные автоматически заполняются, когда первый прокси-сервер получает запрос от приложения. Другие переменные заполняются в сегменте потока ответов прокси. Эти переменные ответа остаются неопределенными до тех пор, пока сегмент ответа не будет выполнен.
- Когда политики выполняются, они могут создавать и заполнять переменные, относящиеся к политике. В документации по каждой политике перечислены все соответствующие переменные, относящиеся к политике.
- Условные потоки обычно оценивают одну или несколько переменных. Вам нужно понимать переменные, если вы хотите создавать условные потоки.
- Многие политики используют переменные в качестве входных или выходных данных. Возможно, переменная, созданная одной политикой, позже используется другой.
- Вы можете получить и установить множество переменных потока из Node.js, используя прямой JavaScript (и нашу объектную модель JavaScript ) или политику JavaCallout , которая выполняет код в Edge.
Связанные примеры кода
Образцы прокси-серверов API находятся на GitHub, их легко загрузить и использовать. Информацию о загрузке и использовании примеров см. в разделе Использование примеров прокси-серверов API . См. Список примеров для описания примеров прокси API и того, что они делают.
Примеры прокси, в которых используются переменные и обработка переменных, включают:
- переменные — демонстрирует, как извлекать и устанавливать переменные на основе транспорта и содержимого сообщений JSON и XML.
- policy-mashup-cookbook — полное приложение, которое использует композицию политики для вызова двух общедоступных API, объединяет результаты и создает расширенный ответ для клиентского приложения. Дополнительные сведения об этом образце см. в разделе Использование композиции политики .
- условная-политика — реализует простое применение условной политики на основе значений переменных.
похожие темы
- Все переменные, которые автоматически заполняются в прокси-сервере API, перечислены в справочнике по переменным потока . В справочнике также перечислены тип и область действия каждой переменной.
- Если вы хотите узнать, какие переменные заполняет конкретная политика, обратитесь к справочному разделу для политики. Например, см. раздел Переменные потока в справочнике по политике квот .