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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например, если к сегменту запроса 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, могут иметь только следующие типы: Number, String, Boolean, null или undefined.

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

Многие правила создают переменные потока в рамках своего обычного выполнения. Все эти переменные, относящиеся к правилам, описаны в документах Справочника по правилам.

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

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

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

В следующем примере Extract Variables анализирует сообщение ответа и сохраняет определенные данные, полученные из ответа. Правило создает две пользовательские переменные: 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, как описано в разделе Визуализация потока прокси-сервера 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 policy и JavaScript policy, а также в коде Node.js.
  • У переменных есть область действия. Например, некоторые переменные заполняются автоматически, когда первый прокси-сервер получает запрос от приложения. Другие переменные заполняются в сегменте потока ответов прокси-сервера. Эти переменные ответа остаются неопределенными до тех пор, пока не будет выполнен сегмент ответа.
  • При выполнении правил могут создаваться и заполняться переменные, относящиеся к определенным правилам. В документации к каждому правилу перечислены все относящиеся к нему переменные.
  • Условные потоки обычно оценивают одну или несколько переменных. Чтобы создавать условные цепочки, необходимо понимать, что такое переменные.
  • Во многих правилах используются входные и выходные переменные. Например, переменная, созданная одним правилом, может использоваться другим.
  • Получать и задавать многие переменные потока в Node.js можно с помощью обычного JavaScript (и нашей объектной модели JavaScript) или правила JavaCallout, которое выполняет код в Edge.

Примеры кода

Примеры прокси-серверов API доступны на GitHub. Их легко скачать и использовать. Подробнее о том, как скачать и использовать примеры прокси API… Описание примеров прокси API и их функций приведено в списке примеров.

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

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

Статьи по теме

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