Правила JavaScript

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

Что

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

Обзор

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

Мы не рекомендуем использовать правила JavaScript для ведения журналов. Правила ведения журналов сообщений лучше подходят для ведения журналов на сторонних платформах, таких как Splunk, Sumo и Loggly. Кроме того, вы можете повысить производительность прокси-сервера API, выполнив правила ведения журналов сообщений в PostClientFlow, который выполняется после того, как ответ был отправлен клиенту.

Правило JavaScript позволяет указать исходный файл JavaScript для выполнения или включить код JavaScript непосредственно в конфигурацию правила с помощью элемента <Source>. В любом случае код JavaScript выполняется, когда выполняется шаг, к которому прикреплено правило. Если выбран вариант исходного файла, исходный код всегда хранится в стандартном месте в пакете прокси: apiproxy/resources/jsc. Вы также можете хранить исходный код в файле ресурсов на уровне среды или организации. Инструкции приведены в разделе Файлы ресурсов. Вы также можете загрузить код JavaScript через редактор прокси-сервисов в интерфейсе Apigee.

Исходные файлы JavaScript всегда должны иметь расширение .js.

Чтобы узнать, какая версия JavaScript поддерживается в настоящее время, ознакомьтесь с разделом Поддерживаемое ПО и поддерживаемые версии.

Видео

Посмотрите короткое видео о том, как создать расширение специальных правил с помощью правил JavaScript.

Примеры

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite">
    <DisplayName>target-rewrite</DisplayName>
    <Properties/>
    <ResourceURL>jsc://js-example.js</ResourceURL>
</Javascript>

Сведения об элементах

В справочнике по элементам описаны элементы и атрибуты правил JavaScript.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false"
        continueOnError="false" enabled="true" timeLimit="200"
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>

</Javascript>

Атрибуты <Javascript>

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

Ниже перечислены атрибуты, относящиеся к этим правилам.

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Элемент <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Элемент <IncludeURL>

Указывает файл библиотеки JavaScript, который нужно загрузить как зависимость для основного файла JavaScript, указанного с помощью элемента <ResourceURL> или <Source>. Скрипты будут оцениваться в том порядке, в котором они указаны в правиле. В коде можно использовать объекты, методы и свойства объектной модели JavaScript.

Добавьте несколько ресурсов зависимостей JavaScript с помощью дополнительных элементов <IncludeURL>.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

Пример

Пример можно найти в разделе Примеры.

Элемент <Property>

Указывает свойство, к которому можно получить доступ из кода JavaScript во время выполнения.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Атрибуты

Пример

Пример можно найти в разделе Примеры.

Элемент <ResourceURL>

Указывает основной файл JavaScript, который будет выполняться в потоке API. Вы можете сохранить этот файл на уровне прокси API (в разделе /apiproxy/resources/jsc пакета прокси API или в разделе "Скрипты" панели навигации редактора прокси API) или на уровне организации или среды, чтобы использовать его в нескольких прокси API, как описано в статье Файлы ресурсов. В коде можно использовать объекты, методы и свойства объектной модели JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>

Пример

Пример можно найти в разделе Примеры.

Элемент <Source>

Позволяет вставлять код JavaScript непосредственно в XML-конфигурацию правила. Вставленный код JavaScript выполняется, когда правило выполняется в потоке API.

Пример

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

Элемент <SSLInfo>

Указывает свойства, используемые для настройки TLS для всех экземпляров HTTP-клиента, созданных правилом JavaScript.

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>

Процесс настройки TLS для клиента HTTP такой же, как и для TargetEndpoint/TargetServer. Подробнее о том, как настроить TLS от Edge до внутреннего сервера…

Примечания

Правила JavaScript не содержат кода. Вместо этого в правилах JavaScript указывается "ресурс" JavaScript и определяется шаг в потоке API, на котором выполняется код JavaScript. Вы можете загрузить скрипт через прокси-редактор интерфейса управления или добавить его в каталог /resources/jsc в прокси API, которые вы разрабатываете локально.

Отладка кода правил JavaScript

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

Чтобы посмотреть операторы печати в Trace, выполните следующие действия:

1. Откройте инструмент трассировки и запустите сеанс трассировки для прокси-сервера, содержащего правила JavaScript.
2. Вызовите прокси.
3. В инструменте трассировки нажмите Выходные данные всех транзакций, чтобы открыть панель выходных данных.

   

4. Здесь будут показываться ваши распечатанные выписки.

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

Переменные потока

По умолчанию это правило не заполняет никакие переменные, но вы можете задавать (и получать) переменные потока в коде JavaScript, вызывая методы объекта контекста. Типичный шаблон выглядит следующим образом:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

Объект контекста является частью модели объектов JavaScript Apigee Edge.

Справочник по ошибкам

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Example error response

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Example fault rule

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

Схема

Каждый тип правил определяется схемой XML (.xsd). Схемы правил доступны на GitHub.

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

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

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

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

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