Правила 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.

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

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются Edge, когда эта политика вызывает ошибку. Эту информацию важно знать, если вы разрабатываете правила обработки ошибок. Дополнительные сведения см. в разделах Что нужно знать об ошибках политики и Обработка ошибок .

Ошибки выполнения

Эти ошибки могут возникнуть при выполнении политики.

Ошибки развертывания

Эти ошибки могут возникнуть при развертывании прокси-сервера, содержащего эту политику.

Переменные неисправности

Эти переменные устанавливаются, когда эта политика вызывает ошибку во время выполнения. Дополнительные сведения см. в разделе Что нужно знать об ошибках политики .

Пример ответа об ошибке

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

Пример правила неисправности

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