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

Вы просматриваете документацию по 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, перечислены в справочнике по переменным потока . В справочнике также перечислены тип и область действия каждой переменной.
  • Если вы хотите узнать, какие переменные заполняет конкретная политика, обратитесь к справочному разделу для политики. Например, см. раздел Переменные потока в справочнике по политике квот .