Объектная модель JavaScript

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

В этой статье рассматривается объектная модель JavaScript Apigee Edge. Если вы планируете использовать правила JavaScript для добавления пользовательского кода JavaScript в прокси API, вам необходимо понимать эту модель.

Объектная модель JavaScript в Edge

Объектная модель JavaScript Apigee Edge определяет объекты со связанными свойствами, которые доступны для кода JavaScript, выполняемого в потоке прокси Apigee Edge. Правило JavaScript используется для того, чтобы прикрепить этот пользовательский код к потоку прокси-сервера API.

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

• context: объект, предоставляющий доступ к контексту сообщения;
• request: сокращенная запись, позволяющая получить доступ к объекту запроса.
• response: сокращенная запись, позволяющая получить доступ к объекту запроса.
• crypto: предоставляет различные хеш-функции.
• print: функция для вывода данных.
• properties: позволяет читать свойства конфигурации в правиле.

Объект контекста

Объект context имеет глобальную область действия. Он доступен везде в потоке прокси-сервера API. У него четыре дочерних объекта: proxyRequest, proxyResponse, targetRequest и targetResponse. Эти дочерние объекты относятся к запросу и ответу, которые передаются в фоновом режиме, то есть к запросу и ответу прокси-сервера или целевого сервиса. Например, если правило JavaScript выполняется в конечной точке прокси-сервера, то объекты context.proxyRequest и context.proxyResponse находятся в области действия. Если код JavaScript выполняется в целевом процессе, то объекты context.targetRequest и context.targetResponse находятся в области действия.

У объекта context также есть свойства и методы, которые подробно описаны в этой статье. Например, в следующем примере кода JavaScript используется свойство context.flow и вызываются методы get/setVariable() для context.

if (context.flow=="PROXY_REQ_FLOW") {
     var username = context.getVariable("request.formparam.user");
     context.setVariable("USER.name", username);
}

Эти методы напрямую взаимодействуют с переменными потока. Значение свойства context.flow – текущая область действия потока. В потоке запросов прокси-сервера для него задано постоянное значение PROXY_REQ_FLOW. Если в целевом ответе задано значение TARGET_RESP_FLOW. Эта константа полезна для выполнения кода, относящегося к определенной области. Геттер позволяет получать переменные потока, а сеттер – задавать их. Эти переменные обычно доступны в потоке прокси и могут использоваться другими правилами.

Подробнее об этом можно узнать в справочнике по объекту контекста ниже.

Объект crypto

Объект crypto добавляет в объектную модель JavaScript базовую криптографическую поддержку с высокой производительностью. Подробную информацию и примеры можно найти в справочнике по объекту crypto.

Объекты запросов и ответов

Объекты request и response – это сокращенные ссылки на окружающий запрос и ответ, то есть на запрос и ответ прокси-сервера или целевой запрос и ответ. Объекты, на которые ссылаются эти переменные, зависят от контекста, в котором выполняется код JavaScript. Если код JavaScript выполняется в потоке конечной точки прокси, то переменные запроса и ответа относятся к context.proxyRequest и context.proxyResponse. Если код JavaScript выполняется в целевом потоке, переменные относятся к context.targetRequest и context.targetResponse.

Функция print()

Объектная модель JavaScript включает функцию print(), которую можно использовать для вывода отладочной информации в инструмент Edge Trace. Подробнее об отладке с помощью операторов JavaScript print()…

Объект properties

Если в конфигурации правила используется элемент , код JavaScript может получить доступ к значениям этих свойств с помощью переменной properties.

Например, если в конфигурации JavaScript есть следующий код:

<Javascript name='JS-1' >
  <Properties>
    <Property name="number">8675309</Property>
    <Property name="firstname">Jenny</Property>
  </Properties>
  <ResourceURL>jsc://my-code.js</ResourceURL>
</Javascript>

Затем в my-code.js вы можете:

  print(properties.firstname);  // prints Jenny
  print(properties.number);  // 8675309

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

В примере ниже указаны "название переменной" и стиль вывода, в который JavaScript должен передавать информацию:

<Javascript name='JS-2' >
  <Properties>
    <Property name="output">my_output_variable</Property>
    <Property name="prettyPrint">true</Property>
  </Properties>
  <ResourceURL>jsc://emit-results.js</ResourceURL>
</Javascript>

var result = { prop1: "something", prop2 : "something else" } ;
if (properties.prettyPrint == "true") {
  context.setVariable(properties.output, JSON.stringify(result, null, 2));
}
else {
  context.setVariable(properties.output, JSON.stringify(result));
}

Справочник по криптообъектам

Объект crypto позволяет выполнять основные криптографические функции хеширования в JavaScript.

Объект crypto имеет глобальную область действия. Он доступен везде в потоке прокси-сервера API. Модуль Crypto позволяет работать со следующими объектами хеширования:

• SHA-1
• SHA256
• SHA512
• MD5

Работа с объектами SHA-1

Вы можете создавать объекты SHA-1, обновлять их и преобразовывать в шестнадцатеричные и base64-значения.

Как создать объект SHA-1

var _sha1 = crypto.getSHA1();

Как обновить объект SHA-1

Синтаксис

_sha1.update(value);

Параметры

• value – строка.

Пример

Чтобы обновить объект SHA-1:

_sha1.update("salt_value");

_sha1.update("some text");

Вернуть объект SHA-1 в виде шестнадцатеричной строки

var _hashed_token = _sha1.digest();

Как вернуть объект SHA-1 в виде строки Base64

var _hashed_token = _sha1.digest64();

Как работать с объектами SHA-256

Вы можете создавать объекты SHA-256, обновлять их и преобразовывать в шестнадцатеричные значения и значения в кодировке Base64.

Как создать объект SHA-256

var _sha256 = crypto.getSHA256();

Как обновить объект SHA-256

Синтаксис

_sha256.update(value);

Параметры

• value – строка.

Пример

Чтобы обновить объект SHA-256, выполните следующие действия:

_sha256.update("salt_value");

_sha256.update("some text");

Верните объект SHA-256 в виде шестнадцатеричной строки

var _hashed_token = _sha256.digest();

Верните объект SHA-256 в виде строки в кодировке Base64.

var _hashed_token = _sha256.digest64();

Работа с объектами SHA-512

Вы можете создавать объекты SHA-512, обновлять их и преобразовывать в шестнадцатеричные и base64-значения.

Как создать новый объект SHA-512

var _sha512 = crypto.getSHA512();

Как обновить объект SHA-512

Синтаксис

_sha512.update(value);

Параметры

• value – строка.

Пример

Чтобы обновить объект SHA-512:

_sha512.update("salt_value");

_sha512.update("some text");

Возвращает объект SHA-512 в виде шестнадцатеричной строки

var _hashed_token = _sha512.digest();

Как вернуть объект SHA-512 в виде строки в кодировке Base64

var _hashed_token = _sha512.digest64();

Работа с объектами MD5

Вы можете создавать объекты MD5, обновлять их и преобразовывать в шестнадцатеричные значения и значения в кодировке Base64.

Как создать новый объект MD5

var _md5 = crypto.getMD5();

Как изменить объект MD5

Синтаксис

_md5.update(value);

Параметры

• value – строка.

Пример

Чтобы изменить объект MD5, выполните следующие действия:

_md5.update("salt_value");

_md5.update("some text");

Как вернуть объект MD5 в виде шестнадцатеричной строки

var _hashed_token = _md5.digest();

Как вернуть объект MD5 в виде строки Base64

var _hashed_token = _md5.digest64();

Поддержка даты и времени для криптовалют

Объект crypto поддерживает форматы даты и времени.

crypto.dateFormat()

Возвращает дату в строковом формате.

Синтаксис

crypto.dateFormat(format, [timezone], [time])

Параметры

• format – (строка) базовый формат этого параметра – java.text.SimpleDateFormat. Пример: "ГГГГ-ММ-ДД ЧЧ:ММ:СС.МММ".
• timezone – (String, необязательный) В основе реализации этого параметра лежит java.util.TimeZone. Этот параметр аналогичен параметру "Часовой пояс" в Google Аналитике. Значение по умолчанию: UTC.
• time – числовое значение временной метки Unix, которое нужно отформатировать (необязательный параметр). По умолчанию: текущее время

Примеры

Получить текущее время с точностью до миллисекунд:

var _now = crypto.dateFormat('yyyy-MM-DD HH:mm:ss.SSS');

Чтобы узнать текущее время в тихоокеанском часовом поясе:

var _pst = crypto.dateFormat('yyyy-MM-DD HH:mm:ss.SSS','PST');

Получить значение, которое будет через 10 секунд:

var _timeNow = Number(context.getVariable('system.timestamp'));
var ten_seconds = crypto.dateFormat('yyyy-MM-DD HH:mm:ss.SSS','PST', _timeNow + 10 * 1000);

Дополнительные примеры. Также ознакомьтесь с документацией по java.text.SimpleDateFormat.

var _pst = crypto.dateFormat('M');

var _pst = crypto.dateFormat('EEE, d MMM yyyy HH:mm:ss Z');

var _pst = crypto.dateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ");

Используйте getHash(), чтобы получить любой из поддерживаемых объектов хеша.

Примеры

var _hash1 = crypto.getHash('MD5');

var _hash2 = crypto.getHash('SHA-1');

var _hash3 = crypto.getHash('SHA-256');

var _hash4 = crypto.getHash('SHA-512');

Пример с криптографией

try {
    // get values to use with hash functions
    var salt = context.getVariable("salt") || 'SomeHardCodedSalt';
    var host = context.getVariable("request.header.Host");
    var unhashed_token = "";

    var _timeNow = Number(context.getVariable('system.timestamp'));
    var now = crypto.dateFormat('yyyy-MM-DD HH:mm:ss.SSS','PST', _timeNow);
    unhashed_token = "|" + now + "|" + host

    // generate a hash with the unhashedToken:
    var sha512 = crypto.getSHA512();
    sha512.update(salt);
    sha512.update(unhashed_token);

    // convert to base64
    var base64_token = sha512.digest64();

    // set headers
    context.setVariable("request.header.now", now);
    context.setVariable("request.header.token", base64_token);

} catch(e) {
    throw 'Error in Javascript';
}

Объект контекста reference

• Краткое описание объекта контекста
• методы объекта контекста
• свойства объекта контекста;
• context object children

Объект context создается для каждой транзакции запроса/ответа, выполняемой прокси-сервером API. Объект context предоставляет методы для получения, установки и удаления переменных, связанных с каждой транзакцией.

Переменные определяют свойства, относящиеся к транзакции. Время суток, местоположение запрашивающего клиента, агент пользователя запрашивающего клиента и URL целевого сервиса – все это примеры переменных, доступных в context. Поэтому context полезен для создания логики, которая опирается на эти свойства для выполнения пользовательского поведения.

Подробнее о переменных потока и правилах извлечения переменных…

контекст сводка объекта

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

Методы объекта context

context.getVariable()

Получает значение стандартной или специальной переменной.

Синтаксис

context.getVariable("variable-name");

Пример

Чтобы получить значение за текущий год:

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

context.setVariable()

Устанавливает значение для пользовательской переменной или для любой записываемой предопределенной переменной.

Синтаксис

context.setVariable("variable-name", value);

Пример

Переменные часто используются, когда прокси-сервер API должен динамически записывать целевой URL. Следующий код JavaScript получает значение переменной USER.name, добавляет его в качестве параметра запроса к URL http://mocktarget.apigee.net?user=, а затем задает для предопределенной переменной target.url это значение.

context.setVariable("target.url", "http://mocktarget.apigee.net/user?user="+context.getVariable("USER.name"));

context.removeVariable()

Удаляет переменную из контекста.

Синтаксис

context.removeVariable('variable-name');

свойства объекта контекста;

context.flow

Свойство flow представляет собой строку, которая идентифицирует текущий поток прокси API. Это свойство используется, чтобы указать поток, к которому прикреплен код JavaScript. Допустимые значения:

• PROXY_REQ_FLOW
• PROXY_RESP_FLOW
• TARGET_REQ_FLOW
• TARGET_RESP_FLOW

Каждое название потока включает PreFlow, PostFlow и все условные потоки, определенные в ProxyEndpoints или TargetEndpoints.

Пример

Задайте HTTP-заголовок только для потока targetRequest:

if (context.flow=="TARGET_REQ_FLOW") {
     context.targetRequest.headers['TARGET-HEADER-X']='foo';
}

Установите контент только в потоке proxyResponse:

if (context.flow=="PROXY_RESP_FLOW") {
     context.proxyResponse.content='bar';
}

context.session

Карта пар "имя/значение", которую можно использовать для передачи объектов между двумя правилами, выполняющимися в одном контексте сообщения.

Пример

Как задать значение в сеансе:

context.session['key']  = 123;

Получите значение из сеанса:

var value = context.session['key']; // 123

context object children

Как показано ниже, полный поток прокси-сервера API включает четыре отдельных этапа, каждый из которых имеет связанный объект сообщения, являющийся дочерним по отношению к объекту контекста:

• context.proxyRequest: входящее сообщение запроса, полученное от клиента, который отправил запрос.
• context.targetRequest: исходящее сообщение запроса, отправленное в серверную службу.
• context.proxyResponse: исходящее ответное сообщение, возвращенное клиенту, отправившему запрос.
• context.targetResponse: входящее сообщение запроса, полученное от внутреннего сервиса.

В разделах ниже описаны методы и свойства этих объектов.

• context.*Request child objects
• Дочерние объекты context.*Response

context.*Дочерние объекты запроса

Для каждой HTTP-транзакции, выполняемой в прокси-сервере API, создаются два объекта запроса: входящий (запрос от клиента) и исходящий (запрос, сгенерированный прокси-сервером API и отправленный целевому серверу).

Объект context имеет дочерние объекты, представляющие эти сообщения запроса: context.proxyRequest и context.targetRequest. Эти объекты позволяют получить доступ к свойствам в потоке запроса, который находится в области действия при выполнении кода JavaScript.

Примечание. Вы также можете использовать объект shorthand request, чтобы получить доступ к этим свойствам в потоке запросов. Объект request относится к context.proxyRequest или context.targetRequest в зависимости от того, на каком этапе выполнения кода JavaScript вы находитесь.

context.*Свойства дочернего объекта Request

context.targetRequest.url = 'http://www.example.com/path?q1=1'
context.targetRequest.protocol ='https';

POST /v1/blogs HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z

context.proxyRequest.headers['Content-Type'];
context.proxyRequest.headers['Authorization'];

application/json
Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z

"?city=PaloAlto&city=NewYork"

context.proxyRequest.queryParams['city'];  // == 'PaloAlto'
context.proxyRequest.queryParams['city'][0]     // == 'PaloAlto'
context.proxyRequest.queryParams['city'][1];    // == 'NewYork'
context.proxyRequest.queryParams['city'].length(); // == 2

POST /v1/blogs HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z

context.proxyRequest.method;

POST

<customer number='1'>
<name>Fred<name/>
<customer/>

var name = context.targetRequest.body.asXML.name;

var number = context.targetRequest.body.asXML.@number;

{
"a":  1 ,
"b" : "2"
}

var a = context.proxyRequest.body.asJSON.a;    // == 1
var b = context.proxyRequest.body.asJSON.b;    // == 2

"vehicle=Car&vehicle=Truck"

v0 = context.proxyRequest.body.asForm['vehicle'][0];
v1 = context.proxyRequest.body.asForm['vehicle'][1];

Дочерние объекты context.*Response

Для каждой HTTP-транзакции, выполняемой в прокси-сервере API, создаются два объекта сообщения ответа: один входящий (ответ от бэкенд-службы) и один исходящий (ответ, отправленный клиенту).

У объекта контекста есть дочерние объекты, представляющие эти сообщения ответа: context.proxyResponse и context.targetResponse. Эти объекты позволяют получать доступ к свойствам в потоке ответов, которые находятся в области действия при выполнении кода JavaScript.

Примечание. Вы также можете использовать объект shorthand response, чтобы получить доступ к этим свойствам из потока ответов. Объект response относится к объекту context.proxyResponse или context.targetResponse в зависимости от того, на каком этапе выполнения кода JavaScript он используется.

Свойства объекта context.*Response

var cookie = context.targetResponse.headers['Set-Cookie'];

var status = context.targetResponse.status.code;   // 200
var msg = context.targetResponse.status.message;   // "OK"

context.targetResponse.content.asXML;
context.targetResponse.content.asJSON;

Использование нотации .asXML

Для работы с XML-документами можно использовать удобную нотацию .asXML. В этом разделе рассказывается, как использовать эту нотацию и чем она отличается от request.content и context.proxyRequest.content.

Пример:

request.content.asXML

или

context.proxyRequest.content.asXML

Обе формы (*.content и *.content.asXML) можно использовать в строковом контексте, и JavaScript преобразует их в строки. В первом случае (*.content) строка включает все объявления и комментарии XML. В последнем случае (*.content.asXML) строковое значение результата очищается от объявлений и комментариев.

Пример

msg.content:

<?xml version="1.0" encoding="UTF-8"?>
<yahoo:error xmlns:yahoo="http://yahooapis.com/v1/base.rng" xml:lang="en-US">
   <yahoo:description>Please provide valid credentials. OAuth oauth_problem="unable_to_determine_oauth_type", realm="yahooapis.com"
   </yahoo:description>
</yahoo:error>
<!-- mg023.mail.gq1.yahoo.com uncompressed/chunked Sat Dec 14 01:23:35 UTC 2013 -->

msg.content.asXML:

<?xml version="1.0" encoding="UTF-8"?>
<yahoo:error xmlns:yahoo="http://yahooapis.com/v1/base.rng" xml:lang="en-US">
   <yahoo:description>Please provide valid credentials. OAuth oauth_problem="unable_to_determine_oauth_type", realm="yahooapis.com"
   </yahoo:description>
</yahoo:error>

Кроме того, вы можете использовать форму .asXML для перехода по иерархии XML, указав названия элементов и атрибутов. Использовать другой синтаксис для перехода по иерархии нельзя.

Отладка с помощью операторов print() в JavaScript

Если вы используете правило JavaScript для выполнения пользовательского кода JavaScript, обратите внимание, что с помощью функции print() можно выводить отладочную информацию в инструмент трассировки. Эта функция доступна непосредственно через объектную модель JavaScript. Пример:

if (context.flow=="PROXY_REQ_FLOW") {
     print("In proxy request flow");
     var username = context.getVariable("request.queryparam.user");
     print("Got query param: " + username);
     context.setVariable("USER.name", username);
     print("Set query param: " + context.getVariable("USER.name"));
}


if (context.flow=="TARGET_REQ_FLOW") {
     print("In target request flow");
     var username = context.getVariable("USER.name");
     var url = "http://mocktarget.apigee.net/user?"
     context.setVariable("target.url", url + "user=" + username);
     print("callout to URL: ", context.getVariable("target.url"));
}

Чтобы посмотреть результат, в нижней части окна трассировки выберите Выходные данные всех транзакций. Выходные данные также можно найти в свойстве трассировки stepExecution-stdout.

Как выполнять вызовы JavaScript с помощью httpClient

Используйте httpClient, чтобы выполнять несколько параллельных асинхронных HTTP-запросов к любому URL из пользовательского кода JavaScript, выполняемого в потоке прокси-сервера API. Объект httpClient предоставляется моделью объекта JavaScript Apigee Edge.

Об объекте httpClient

Объект httpClient доступен для пользовательского кода JavaScript, выполняемого в Apigee Edge, через объектную модель JavaScript. Чтобы прикрепить собственный код JavaScript к прокси-серверу API, используйте правило JavaScript. При выполнении правила будет запущен собственный код JavaScript.

Объект httpClient полезен при разработке составных сервисов или гибридных приложений. Например, вы можете объединить несколько вызовов к серверной части в один метод API. Этот объект часто используется в качестве альтернативы правилу ServiceCallout.

Вот как обычно используется этот инструмент. Создайте объект Request, назначьте ему URL (например, для бэкенд-службы, которую вы хотите вызвать) и вызовите httpClient.send с этим объектом Request.

var myRequest = new Request();
myRequest.url = "http://www.example.com";
var exchangeObj = httpClient.send(myRequest);

Справочник по httpClient

Клиент HTTP предоставляет два метода: get() и send().

httpClient.get()

Удобный метод для простых HTTP-запросов GET без поддержки HTTP-заголовков.

Использование

var exchangeObj = httpClient.get(url);

Возвраты

Метод возвращает объект exchange. У этого объекта нет свойств, но есть следующие методы:

• isError() (логическое значение). Возвращает значение true, если httpClient не удалось подключиться к серверу. Коды статуса HTTP 4xx и 5xx приводят к ошибке isError() false, поскольку подключение было установлено и был возвращен действительный код ответа. Если функция isError() возвращает значение true, то вызов функции getResponse() возвращает код JavaScript undefined.
• isSuccess() (логическое значение). Возвращает значение true, если отправка была завершена успешно.
• isComplete() (логическое значение). Возвращает значение true, если запрос выполнен.
• waitForComplete() – приостанавливает поток до завершения запроса (успешного или с ошибкой).
• getResponse() – объект ответа, если запрос httpClient.send() был выполнен успешно. Возвращаемый объект имеет те же методы и свойства, что и объект context.proxyResponse. Подробнее об объекте context…
• getError() (строка): если вызов httpClient.send() привел к ошибке, возвращает сообщение об ошибке в виде строки.

Пример

Отправьте полностью настроенный объект Request, содержащий свойства HTTP-запроса. Используйте неблокирующий обратный вызов для обработки ответа.

// Add the required the headers for making a specific API request
var headers = {'X-SOME-HEADER' : 'some value' };
// Make a GET API request along with headers
var myRequest = new Request("http://www.example.com","GET",headers);

// Define the callback function and process the response from the GET API request
function onComplete(response,error) {
 // Check if the HTTP request was successful
    if (response) {
      context.setVariable('example.status', response.status);
     } else {
      context.setVariable('example.error', 'Woops: ' + error);
     }
}

// Specify the callback Function as an argument
httpClient.get(myRequest, onComplete);

Как использовать правила JavaScript

Используйте правила JavaScript, чтобы прикрепить собственный код JavaScript к потоку прокси. Подробнее о правилах использования JavaScript…

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

• Правила использования JavaScript
• Объектная модель JavaScript
• Основные примеры и инструкции можно найти в статье Программирование прокси API с помощью JavaScript.
• Примеры рабочего кода JavaScript можно найти в образцах Apigee Edge на GitHub.

Статьи сообщества Apigee

В сообществе Apigee вы найдете следующие статьи:

• Как обрабатывать заголовки с несколькими значениями в JavaScript?
• Книга антипаттернов Apigee Edge