Шаблоны сообщений

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

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

Что такое шаблон сообщения?

Шаблон сообщения позволяет выполнять замену строк переменных в определенных элементах правил и TargetEndpoint. Эта функция позволяет динамически заполнять строки при выполнении прокси.

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

Также ознакомьтесь с информацией о том, где можно использовать шаблоны сообщений.

Пример

Например, правило "Назначить сообщение" позволяет использовать шаблон сообщения в элементе <Payload>:

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="application/json">
      {"name":"Alert", "message":"You entered an invalid username: {user.name}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

В приведенном выше примере значение переменной потока user.name (в фигурных скобках) будет вычислено и подставлено в строку полезной нагрузки во время выполнения. Например, если в поле "Сообщение" указано user.name=jdoe, то в полезной нагрузке будет указано You entered an invalid username: jdoe. Если переменную не удается разрешить, выводится пустая строка.

Пример

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

<AssignMessage name='AM-QuotaViolationMessage'>
  <Description>message for quota exceeded</Description>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header>
      <Header name='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header>
      <Header name='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header>
    </Headers>
    <Payload contentType='application/json'>{
  "error" : {
    "message" : "you have exceeded your quota",
    "clientId" : "{request.queryparam.apikey}"
  }
}
    </Payload>
    <StatusCode>429</StatusCode>
    <ReasonPhrase>Quota Exceeded</ReasonPhrase>
  </Set>
</AssignMessage>

В правиле AssignMessage следующие элементы в элементе <Set> поддерживают шаблоны сообщений:

• Заголовок
• QueryParam
• FormParam
• PayLoad
• Версия
• Глагол
• Путь
• StatusCode
• ReasonPhrase

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

Когда выполняется это правило:

• Элементы заголовка получают значения указанных переменных потока.
• Полезная нагрузка содержит как обычный текст, так и переменные (client_id заполняется динамически).
• StatusCode и ReasonPhrase содержат только текст, но при необходимости вы можете использовать в этих элементах шаблоны сообщений.

Пример

В определении TargetEndpoint прокси-сервера дочерние элементы <SSLInfo> поддерживают шаблоны сообщений. По аналогии с правилами переменные потока в фигурных скобках заменяются при выполнении прокси.

<TargetEndpoint name="default">
  …
  <HTTPTargetConnection>
    <SSLInfo>
        <Enabled>{myvars.ssl.enabled}</Enabled>
        <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
        <KeyStore>{myvars.ssl.keystore}</KeyStore>
        <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
        <TrustStore>{myvars.ssl.trustStore}</TrustStore>
    </SSLInfo>

  </HTTPTargetConnection>
  …
</TargetEndpoint>

Где можно использовать шаблоны сообщений?

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

Правила, в которых можно использовать шаблоны сообщений

Элементы TargetEndpoint, которые принимают шаблоны сообщений

Синтаксис шаблона сообщения

В этом разделе описаны правила, которые необходимо соблюдать при использовании шаблонов сообщений.

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

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

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

<Set>
    <Headers>
        <Header name="x-h1">"Hello {user.name}"</Header>
        <Header name="x-h1">Hello {user.name}</Header>
    </Headers>
</Set>

Как задавать значения по умолчанию в шаблонах писем

Если переменную шаблона не удается разрешить, Edge подставляет пустую строку. Однако вы можете задать значение по умолчанию, выполнив следующие действия:

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

В приведенном выше примере, если переменную request.header.id нельзя разрешить, ее значение заменяется на Unknown. Пример:

Test message. id = Unknown

В выражениях функций не должно быть пробелов.

Пробелы не допускаются ни в одной части выражений функций шаблонов сообщений. Пример:

Допустимый:

{substring(alpha,0,4)}
{createUuid()}
{randomLong(10)}

Примеры названий, где нет нужных сведений:

{substring( alpha, 0, 4 )}
{ createUuid( ) }
{randomLong( 10 )}

Устаревший синтаксис для полезных нагрузок JSON

В версиях Edge до выпуска Cloud 16.08.17 нельзя использовать фигурные скобки для обозначения ссылок на переменные в полезных нагрузках JSON. В более ранних версиях для указания символов-разделителей нужно было использовать атрибуты variablePrefix и variableSuffix, а затем заключать в них названия переменных, как показано ниже:

<Set>
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
    {"name":"foo", "type":"@variable_name#"}
  </Payload>
</Set>

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

Как использовать функции шаблонов сообщений

Edge предоставляет набор функций, которые можно использовать в шаблонах сообщений для экранирования, кодирования, хеширования и форматирования строковых переменных.

Функции шаблонов сообщений подробно описаны в справочнике по функциям шаблонов сообщений.

Пример: toLowerCase()

Используйте встроенную функцию toLowerCase(), чтобы преобразовать строковую переменную в нижний регистр:

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
        <Headers>
            <Header name="x-h1">Test header: {toLowerCase(foo.bar:FOO)}</Header>
        </Headers>
    </Set>
</AssignMessage>

Если переменная потока foo.bar будет разрешена, то все ее символы будут в нижнем регистре. Если значение foo.bar не определено, используется значение по умолчанию FOO, которое преобразуется в строчные буквы. Пример:

Test header: foo

Пример: escapeJSON()

Предположим, что ваше серверное приложение возвращает ответ в формате JSON, содержащий действительные экранирующие символы. Пример:

{
      "code": "INVALID",
      "user_message": "Invalid value for \"logonId\" check your input."
}

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

Ниже приведен пример правила Extract Variables, которое извлекает информацию user_message в переменную standard.systemMessage:

<ExtractVariables name="EV-BackendErrorResponse">
    <DisplayName>EV-BackendErrorResponse</DisplayName>
    <JSONPayload>
        <Variable name="standard.systemMessage">
            <JSONPath>$.user_message</JSONPath>
        </Variable>
    </JSONPayload>
</ExtractVariables>

Ниже приведен пример вполне допустимого правила Assign Message, которое добавляет извлеченную переменную в полезную нагрузку ответа (ответ прокси):

<AssignMessage name="AM-SetStandardFaultResponse">
    <DisplayName>AM-SetStandardFaultResponse</DisplayName>
    <Set>
        <Payload contentType="application/json">
           {
              "systemMessage": "{standard.systemMessage}"
           }
        </Payload>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

К сожалению, возникла проблема. Правило Extract Variables удалило экранированные кавычки вокруг части сообщения. Это означает, что ответ, возвращенный клиенту, является недопустимым JSON-файлом. Это явно не то, что вы хотели!

{
    "systemMessage": "Invalid value for "logonId" check your input."
}

Чтобы обойти эту проблему, можно изменить правило Assign Message, чтобы использовать функцию шаблона сообщения, которая экранирует кавычки в JSON. Функция escapeJSON() экранирует кавычки и другие специальные символы, которые встречаются в выражении JSON:

<AssignMessage name="AM-SetStandardFaultResponse">
    <DisplayName>AM-SetStandardFaultResponse</DisplayName>
    <Set>
        <Payload contentType="application/json">
           {
              "systemMessage": "{escapeJSON(standard.systemMessage)}"
           }
        </Payload>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Функция экранирует встроенные кавычки, в результате чего получается действительный код JSON, то есть именно то, что вам нужно:

{
      "systemMessage": "Invalid value for \"logonId\" check your input.",
}

Шаблон сообщения – это функция динамической замены строк, которую можно использовать в некоторых правилах и определениях TargetEndpoint. Функции шаблонов сообщений позволяют выполнять полезные операции, такие как хеширование, обработка строк, экранирование символов и т. д.

Например, в следующем правиле AssignMessage функция toLowerCase() используется в шаблоне сообщения:

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Test header: {Hello, toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

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

Хеш-функции

Вычисляет значение хеша и возвращает его строковое представление.

Шестнадцатеричные хеш-функции

Вычисляет значение хеша и возвращает его строковое представление в виде шестнадцатеричного числа.

Синтаксис

Аргументы

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

Примеры

Вызов функции:

sha256Hex('abc')

Результат.

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Вызов функции:

var str = 'abc';
sha256Hex(str)

Результат.

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Хеш-функции Base64

Вычисляет значение хеша и возвращает его строковое представление в кодировке Base64.

Синтаксис

Аргументы

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

Примеры

Вызов функции:

sha256Base64('abc')

Результат.

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Вызов функции:

var str = 'abc';
sha256Base64(str)

Результат.

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

Строковые функции

Выполнять операции со строками в шаблоне письма.

Функции кодирования Base64

Кодировать и декодировать строки с помощью схемы кодирования Base64.

Синтаксис

Аргументы

string – строка, которую нужно закодировать или декодировать. Может быть строковым литералом или строковой переменной процесса.

Пример

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header>
       </Headers>
    </Set>
</AssignMessage>

Функции преобразования регистра

Преобразование строки в верхний или нижний регистр.

Синтаксис

Аргументы

string – строка, которую нужно преобразовать. Может быть строковым литералом или строковой переменной процесса.

Пример

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

Функция подстроки

Возвращает символы между начальным и конечным индексами заданной строки.

Синтаксис

substring(str,start_index,end_index)

Аргументы

• str – строковый литерал или переменная потока строк.
• start_index – начальный индекс в строке.
• end_index – конечный индекс строки (необязательно). Если не указан, конечным индексом будет конец строки.

Примеры

Предположим, что существуют следующие переменные потока:

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

Функция "Заменить все"

Применяет регулярное выражение к строке и заменяет все совпадения заданным значением.

Синтаксис

replaceAll(string,regex,value)

Аргументы

• string – строка или переменная потока строк, в которой нужно выполнить замену.
• regex – регулярное выражение.
• value – значение, которое нужно подставить вместо всех совпадений с регулярным выражением в строке.

Примеры

Предположим, что существуют следующие переменные потока:

Ниже приведены результаты вызовов функций, в которых используются эти переменные:

Функция Replace First

Заменяет только первое вхождение указанного регулярного выражения в строке.

Синтаксис

replaceFirst(string,regex,value)

Аргументы

• string – строка или переменная потока строк, в которой нужно выполнить замену.
• regex – регулярное выражение.
• value – значение, которое нужно подставить вместо совпадений с регулярным выражением в строке.

Функции экранирования и кодирования символов

Функции, которые экранируют или кодируют специальные символы в строке.

Синтаксис

Аргументы

string – строка, которую нужно экранировать. Может быть строковым литералом или строковой переменной процесса.

Примечания

XML 1.1 может представлять определенные управляющие символы, но не может представлять нулевой байт или непарные суррогатные кодовые точки Unicode, даже после экранирования. Функция escapeXML11() удаляет символы, которые не входят в следующие диапазоны:

[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

Функция escapeXML11() экранирует символы из следующих диапазонов:

[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]

Примеры

Предположим, что существует переменная потока food со значением "bread" & "butter". Функция:

{escapeHTML(food)}

Результаты:

Функции для работы с форматами времени

Возвращает строковое представление времени, отформатированное в местном часовом поясе или в формате UTC.

Синтаксис

Аргументы

• format – строка формата даты и времени. Может быть строковым литералом или строковой переменной.
• str – строка или переменная потока строк, содержащая значение времени. Значение может быть указано в секундах или миллисекундах с начала эпохи.

Примеры

Предположим, что у вас следующие значения и местный часовой пояс – тихоокеанский:

• epoch_time_ms = 1494390266000
• epoch_time = 1494390266
• fmt1 = yyyy-MM-dd
• fmt2 = yyyy-MM-dd HH-mm-ss
• fmt3 = yyyyMMddHHmmss

Функции возвращают следующие результаты:

Функция	Результат
timeFormatMs(fmt1,epoch_time_ms)	2017-05-09
timeFormat(fmt1,epoch_time)	2017-05-09
timeFormat(fmt2,epoch_time)	2017-05-09 21:24:26
timeFormat(fmt3,epoch_time)	20170509212426
timeFormatUTC(fmt1,epoch_time)	2017-05-10
timeFormatUTC(fmt2,epoch_time)	2017-05-10 04:24:26
timeFormatUTC(fmt3,epoch_time)	20170510042426

Функции для вычисления HMAC

Функции расчета HMAC – это альтернатива правилу HMAC, которое используется для вычисления HMAC. Эти функции полезны при выполнении каскадного вычисления HMAC, когда выходные данные одного HMAC используются в качестве ключа для второго HMAC.

Синтаксис

Функция	Описание
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]])	Вычисляет HMAC с хеш-функцией SHA-224.
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]])	Кодирует HMAC с помощью хеш-функции SHA-256.
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]])	Кодирует HMAC с помощью хеш-функции SHA-384.
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]])	Кодирует HMAC с помощью хеш-функции SHA-512.
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]])	Кодирует HMAC с помощью хеш-функции MD5.
hmacSha1(key, valueToSign [,keyencoding[,outputencoding]])	Кодирует HMAC с помощью алгоритма шифрования SHA-1.

Аргументы

• key – (обязательный) секретный ключ, закодированный в виде строки, который используется для вычисления HMAC.
• valueToSign – (обязательный) сообщение, которое нужно подписать. Укажите строку.
• keyencoding – (необязательный параметр) строка секретного ключа будет декодирована в соответствии с указанной кодировкой. Допустимые значения: hex, base16, base64, utf-8. По умолчанию: utf-8
• outputencoding – (необязательный параметр) задает алгоритм кодирования, который будет использоваться для выходных данных. Допустимые значения: hex, base16, base64. Регистр символов не учитывается. Значения hex и base16 являются синонимами. По умолчанию: base64

Примеры

В этом примере используется правило AssignMessage, чтобы вычислить HMAC-256 и назначить его переменной потока:

<AssignMessage name='AM-HMAC-1'>
  <AssignVariable>
    <Name>valueToSign</Name>
    <Template>{request.header.apikey}.{request.header.date}</Template>
  </AssignVariable>
  <AssignVariable>
    <Name>hmac_value</Name>
    <Template>{hmacSha256(private.secretkey,valueToSign)}</Template>
  </AssignVariable>
</AssignMessage>

В этом примере показано, как создать каскадный HMAC, который можно использовать в процессе подписи AWS Signature v4. В примере используется правило AssignMessage для создания пяти уровней каскадированного HMAC, которые используются для вычисления подписи AWS Signature v4:

<AssignMessage name='AM-HMAC-AWS-1'>
  <!-- 1 -->
  <AssignVariable>
    <Name>DateValue</Name>
    <Template>{timeFormatUTCMs('yyyyMMdd',system.timestamp)}</Template>
  </AssignVariable>
  <!-- 2 -->
  <AssignVariable>
    <Name>FirstKey</Name>
    <Template>AWS4{private.secret_aws_access_key}</Template>
  </AssignVariable>
  <!-- 3 -->
  <AssignVariable>
    <Name>DateKey</Name>
    <Template>{hmacSha256(FirstKey,DateValue,'utf-8','base16')}</Template>
  </AssignVariable>
  <!-- 4 -->
  <AssignVariable>
    <Name>DateRegionKey</Name>
    <Template>{hmacSha256(DateKey,aws_region,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 5 -->
  <AssignVariable>
    <Name>DateRegionServiceKey</Name>
    <Template>{hmacSha256(DateRegionKey,aws_service,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 6 -->
  <AssignVariable>
    <Name>SigningKey</Name>
    <Template>{hmacSha256(DateRegionServiceKey,'aws4_request','base16','base16')}</Template>
  </AssignVariable>
  <!-- 7 -->
  <AssignVariable>
    <Name>aws4_hmac_value</Name>
    <Template>{hmacSha256(SigningKey,stringToSign,'base16','base16')}</Template>
  </AssignVariable>
</AssignMessage>

Другие функции

Как создать функцию UUID

Создает и возвращает UUID.

Синтаксис

createUuid()

Аргументы

Нет.

Пример

{createUuid()}

Пример результата:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Функция генератора случайных длинных строк

Возвращает случайное длинное целое число.

Синтаксис

randomLong(args)

Аргументы

• Если аргументы не указаны, функция возвращает случайное длинное целое число, вычисленное классом Java SecureRandom.
• Если указан один аргумент, он считается минимальным значением для вычисления.
• Если указан второй аргумент, он считается максимальным значением для вычисления.

Пример

{random()}

Результат будет выглядеть примерно так:

5211338197474042880

Генератор текста на основе регулярных выражений

Создает текстовую строку, соответствующую заданному регулярному выражению.

Синтаксис

xeger(regex)

Аргумент

regex – регулярное выражение.

Пример

В этом примере создается семизначная строка без нулей:

xeger('[1-9]{7}')

Пример результата:

9857253

Функция объединения со значением NULL

Функция firstnonnull() возвращает значение самого левого аргумента, не являющегося нулевым.

Синтаксис

firstnonnull(var1,varnn>)

Аргумент

var1 – контекстная переменная.

var_n – одна или несколько контекстных переменных. Вы можете задать для крайнего правого аргумента строку, чтобы указать резервное значение (которое будет задано, если ни один из аргументов слева не задан).

Примеры

В таблице ниже показано, как использовать эту функцию.

Шаблон	Var1	Var2	Var3	Результат
{firstnonnull(var1,var2)}	Не задано	foo	Н/Д	foo
{firstnonnull(var1,var2)}	foo	bar	Н/Д	foo
{firstnonnull(var1,var2)}	foo	Не задано	Н/Д	foo
{firstnonnull(var1,var2,var3)}	foo	bar	baz	foo
{firstnonnull(var1,var2,var3)}	Не задано	bar	baz	bar
{firstnonnull(var1,var2,var3)}	Не задано	Не задано	baz	baz
{firstnonnull(var1,var2,var3)}	Не задано	Не задано	Не задано	null
{firstnonnull(var1)}	Не задано	Н/Д	–	null
{firstnonnull(var1)}	foo	–	–	foo
{firstnonnull(var1,var2)}	""	bar	Н/Д	""
{firstnonnull(var1,var2,'fallback value')}	null	null	fallback value	fallback value

Функция XPath

Применяет выражение XPath к переменной XML.

Синтаксис

xpath(xpath_expression,xml_string,[datatype])

Аргументы

xpath_expression – выражение XPath.

xml_string – переменная потока или строка, содержащая XML.

datatype – (необязательный параметр) указывает желаемый тип возвращаемого значения запроса. Может быть набором узлов, узлом, числом, логическим значением или строкой. По умолчанию используется набор узлов. Обычно лучше оставить значение по умолчанию.

Пример 1

Предположим, что эти контекстные переменные определяют строку XML и выражение XPath:

xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>"
xpath = "/tag/tagid"

Функция xpath() используется в правиле AssignMessage следующим образом:

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath(xpath,xml)}</Template>
  </AssignVariable>
</AssignMessage><

Функция возвращает значение <tagid>250397</tagid>. Это значение помещается в переменную контекста extracted_tag.

Пример 2

Если вам нужно только значение узла, используйте функцию text() следующим образом:

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath('/tag/tagid/text()',xml)}</Template>
  </AssignVariable>
</AssignMessage>

В результате этой операции контекстная переменная extracted_tag будет иметь значение 250397.

Если выбрано несколько узлов, результатом функции xpath() будут все значения выбранных узлов, объединенные запятой.

Пример 3. Пространства имен XML

Чтобы указать пространство имен, добавьте дополнительные параметры, каждый из которых представляет собой строку, похожую на следующую: prefix:namespaceuri. Например, функция xpath(), которая выбирает дочерний элемент тела SOAP, может выглядеть так:

<AssignMessage>
  <AssignVariable>
    <Name>soapns</Name>
    <Value>soap:http://schemas.xmlsoap.org/soap/envelope/</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>xpathexpression</Name>
    <Value>/soap:Envelope/soap:Body/*</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>extracted_element</Name>
    <Template>{xpath(xpathexpression,xml,soapns)}</Template>
  </AssignVariable>
</AssignMessage>

Для дополнительных пространств имен можно добавить до 10 дополнительных параметров в функцию xpath().

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

{xpath('/tag/tagid/text()',xml)}

Если выражение XPath содержит префиксы пространства имен (и двоеточия), вам нужно присвоить это выражение XPath переменной и указать название переменной, а не само выражение.

{xpath(xpathexpression,xml,ns1)}

Пример 4. Указание желаемого типа возвращаемого значения

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

Некоторые запросы XPath могут возвращать числовые или логические значения. Например, функция count() возвращает число. Вот пример допустимого запроса XPath:

count(//Record/Fields/Pair)

Этот действительный запрос возвращает логическое значение:

count(//Record/Fields/Pair)>0

В таких случаях вызовите функцию xpath() с третьим параметром, указывающим тип:

{xpath(expression,xml,'number')}
{xpath(expression,xml,'boolean')}

Если третий параметр содержит двоеточие, он интерпретируется как аргумент пространства имен. В противном случае он будет считаться желаемым типом возвращаемого значения. В этом случае, если третий параметр не является одним из допустимых значений (без учета регистра), функция xpath() по умолчанию возвращает набор узлов.

Функция JSON Path

Применяет выражение JSON Path к переменной JSON.

Синтаксис

jsonPath(json-path,json-var,want-array)

Аргументы

• (Обязательно) json-path: (строка) выражение JSON Path.
• (Обязательно) json-var: (строка) переменная потока или строка, содержащая JSON.
• (Необязательно) want-array: (строка). Если для этого параметра задано значение 'true' и набор результатов представляет собой массив, возвращаются все элементы массива. Если задано другое значение или параметр опущен, возвращается только нулевой элемент массива результатов. Если набор результатов не является массивом, то третий параметр, если он присутствует, игнорируется.

Пример 1

Если это шаблон сообщения:

The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}

а объект the_json_variable содержит:

{
  "results" : [
    {
      "address" : {
        "line1" : "18250 142ND AV NE",
        "city" : "Woodinville",
        "state" : "Washington",
        "zip" : "98072"
      },
      "name" : "Fred Meyer"
    },
    {
      "address" : {
        "line1" : "1060 West Addison Street",
        "city" : "Chicago",
        "state" : "Illinois",
        "zip" : "60613"
      },
      "name" : "Mae West"
    }
  ]
} 

Результат функции:

The address is 1060 West Addison Street

Обратите внимание, что в этом случае набор результатов представляет собой один элемент (а не массив элементов). Если бы набор результатов был массивом, то возвращался бы только нулевой элемент массива. Чтобы вернуть весь массив, вызовите функцию с параметром 'true' в качестве третьего аргумента, как показано в следующем примере.

Пример 2

Если шаблон сообщения выглядит так:

{jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}

а объект the_json_variable содержит:

{
  "results" : [
     {
      "config": {
        "quota": [
          {
            "appname": "A",
            "operation": "ManageOrder",
            "value": "900"
          },
          {
            "appname": "B",
            "operation": "ManageOrder",
            "value": "1000"
          },
          {
            "appname": "B",
            "operation": "SubmitOrder",
            "value": "800"
          }
        ]
      }
    }
  ]
} 

Результат функции:

['A','B']