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

Вы просматриваете документацию 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, примерно так же, как оператор переключения работает в программировании.

    Например, политика возврата ошибки может выполняться только тогда, когда установлена ​​конкретная переменная потока. Наконец, вы можете получать и устанавливать переменные потока в целевом приложении 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 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
целевой ответ Сегмент ответа 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, ограничены числовыми, строковыми, логическими, нулевыми или неопределенными значениями.

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

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

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

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

Политика 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» .

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