Правило AssignMessage

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

Что

Правило AssignMessage изменяет или создает новые сообщения запросов и ответов во время выполнения потока прокси-сервера API. Правило позволяет выполнять с такими письмами следующие действия:

  • Добавлять в сообщение новые параметры формы, заголовки или параметры запроса.
  • Копирование существующих свойств из одного сообщения в другое.
  • Удаление заголовков, параметров запросов, параметров форм и/или полезной нагрузки из сообщения.
  • Задавать значения существующих свойств в сообщении.

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

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

Элемент <AssignMessage>

Определяет правило AssignMessage.

Значение по умолчанию См. вкладку Правила по умолчанию ниже.
Обязательно? Обязательно
Тип Сложный объект
Родительский элемент –
Дочерние элементы <Add>
<AssignTo>
<AssignVariable>
<Copy>
<DisplayName>
<IgnoreUnresolvedVariables>
<Remove>
<Set>

Элемент <AssignMessage> использует следующий синтаксис:

Синтаксис

Элемент <AssignMessage> использует следующий синтаксис:

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <!-- All AssignMessage child elements are optional -->
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>

  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>

  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
    <Value>variable_value</Value>
  </AssignVariable>

  <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>[false|true]</ReasonPhrase>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>

  <DisplayName>policy_display_name</DisplayName>

  <IgnoreUnresolvedVariables>[true|false]
  </IgnoreUnresolvedVariables>

  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>

  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>path</Path>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>

</AssignMessage>

Правило по умолчанию

В следующем примере показаны настройки по умолчанию, которые используются при добавлении правила AssignMessage в поток в интерфейсе Edge:

<AssignMessage continueOnError="false" enabled="true" name="assign-message-default">
  <DisplayName>Assign Message-1</DisplayName>
  <Properties/>
  <Copy source="request">
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <Payload/>
    <Verb/>
    <StatusCode/>
    <ReasonPhrase/>
    <Path/>
  </Copy>
  <Remove>
    <Headers>
      <Header name="h1"/>
    </Headers>
    <QueryParams>
      <QueryParam name="q1"/>
    </QueryParams>
    <FormParams>
      <FormParam name="f1"/>
    </FormParams>
    <Payload/>
  </Remove>
  <Add>
    <Headers/>
    <QueryParams/>
    <FormParams/>
  </Add>
  <Set>
    <Headers/>
    <QueryParams/>
    <FormParams/>
    <!-- <Verb>GET</Verb> -->
    <Path/>
  </Set>
  <AssignVariable>
    <Name>name</Name>
    <Value/>
    <Ref/>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Когда вы вставляете новое правило AssignMessage в интерфейсе Edge, шаблон содержит заглушки для всех возможных операций. Как правило, вы выбираете, какие операции хотите выполнить с этим правилом, и удаляете остальные дочерние элементы. Например, если вы хотите выполнить операцию копирования, используйте элемент <Copy> и удалите из правила элементы <Add>, <Remove> и другие дочерние элементы, чтобы сделать его более понятным.

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

Атрибут По умолчанию Необходимый? Описание
name Н/Д Необходимый

Внутреннее имя политики. Значение атрибута name может содержать буквы, цифры, пробелы, дефисы, символы подчеркивания и точки. Это значение не может превышать 255 символов.

При необходимости используйте элемент <DisplayName> , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

continueOnError ЛОЖЬ Необязательный Установите значение «false», чтобы возвращать ошибку при сбое политики. Это ожидаемое поведение для большинства политик. Установите значение «true», чтобы выполнение потока продолжалось даже после сбоя политики.
enabled истинный Необязательный Установите значение «true», чтобы применить политику. Установите значение «false», чтобы «отключить» политику. Политика не будет применяться, даже если она остается присоединенной к потоку.
async ЛОЖЬ Устаревший Этот атрибут устарел.

В таблице ниже приведено общее описание дочерних элементов <AssignMessage>.

Дочерний элемент Обязательно? Описание
Стандартные операции
<Add> Необязательно Добавляет информацию в объект сообщения, указанный элементом <AssignTo>.

<Add> добавляет в письмо заголовки или параметры, которых нет в исходном письме. Чтобы перезаписать существующие заголовки или параметры, используйте элемент <Set>.
<Copy> Необязательно Копирует информацию из сообщения, указанного атрибутом source, в объект сообщения, указанный элементом <AssignTo>.
<Remove> Необязательно Удаляет указанные элементы из переменной сообщения, заданной в элементе <AssignTo>.
<Set> Необязательно Заменяет значения существующих свойств в запросе или ответе, указанном в элементе <AssignTo>.

<Set> перезаписывает заголовки или параметры, которые уже существуют в исходном письме. Чтобы добавить новые заголовки или параметры, используйте элемент <Add>.
Другие дочерние элементы
<AssignTo> Необязательно Указывает, к какому сообщению применяется правило AssignMessage. Это может быть стандартный запрос или ответ, а также новое специальное сообщение.
<AssignVariable> Необязательно Присваивает значение переменной потока. Если переменной нет, <AssignVariable> создаст ее.
<IgnoreUnresolvedVariables> Необязательно Определяет, прекращается ли обработка при обнаружении неразрешенной переменной.

Каждый из этих дочерних элементов описан в следующих разделах.

Примеры

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

1. Добавьте заголовок

В следующем примере в запрос добавляется заголовок с элементом <Add>:

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

2. Удалите полезную нагрузку

В следующем примере полезная нагрузка удаляется из ответа с помощью элемента <Remove>:

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

3. Изменить ответ

В следующем примере показано, как изменить существующий объект ответа, добавив в него заголовок:

<AssignMessage name="AM-modify-response">
  <Set>
    <Headers>
      <Header name="Cache-Hit">{lookupcache.LookupCache-1.cachehit}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>false
  </IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

В этом примере новое сообщение не создается. Вместо этого он изменяет существующее сообщение ответа, добавляя HTTP-заголовок.

Поскольку в этом примере в качестве имени переменной в элементе <AssignTo> указано response, это правило изменяет объект ответа, который изначально был задан с данными, возвращенными целевым сервером.

HTTP-заголовок, добавленный в ответное сообщение этим правилом, получен из переменной, заполненной правилом LookupCache. Поэтому ответ, измененный этим правилом, содержит HTTP-заголовок, который указывает, были ли результаты получены из кеша. Заголовки в ответе могут быть полезны для отладки и устранения неполадок.

4. Настройте динамический контент

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

Чтобы встроить переменные потока Edge в полезную нагрузку XML, заключите назначенную переменную в фигурные скобки, например {prefix.name}.

В следующем примере значение переменной потока заголовка HTTP user-agent встраивается в элемент XML с названием User-agent:

<AssignMessage name="AM-set-dynamic-content">
  <AssignTo>response</AssignTo>
  <Set>
    <Payload contentType="text/xml">
      <User-agent>{request.header.user-agent}</User-agent>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false
  </IgnoreUnresolvedVariables>
</AssignMessage>

В полезную нагрузку JSON можно вставлять переменные, используя атрибуты variablePrefix и variableSuffix с символами-разделителями, как показано в примере ниже.

<AssignMessage name="set-payload">
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
  {
     "user-agent": "@request.header.user-agent#"
  }
  </Payload>
</AssignMessage>

Полный список переменных потока приведен в справочнике по переменным потока.

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

5. Удалите параметр запроса

В примере ниже из запроса удаляется параметр apikey:

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

При использовании правила VerifyAPIKey для аутентификации пользователей рекомендуется удалять параметр запроса apikey из сообщения запроса. Это делается для того, чтобы конфиденциальная информация о ключе не передавалась целевому серверу.

6. Настройка и получение переменных

В следующем примере используются три правила Assign Message:

  1. Создает в запросе три переменные потока со статическими значениями.
  2. Динамически получает переменные потока во второй политике в потоке запросов.
  3. Задает их в полезной нагрузке ответа.
<!-- Policy #1: Set variables in the request -->

<AssignMessage name="AM-set-variables">
    <!-- Create a variable named myAppSecret -->
    <AssignVariable>
        <Name>myAppSecret</Name>
        <Value>42</Value>
    </AssignVariable>
    <!-- Create a variable named config.environment -->
    <AssignVariable>
        <Name>config.environment</Name>
        <Value>test</Value>
    </AssignVariable>
    <!-- Create a variable named config.protocol -->
    <AssignVariable>
        <Name>config.protocol</Name>
        <Value>gopher</Value>
    </AssignVariable>
</AssignMessage>

В первом правиле элемент <AssignVariable> создает и задает три переменные в запросе. Каждый элемент <Name> указывает название переменной, а <Value> – ее значение.

Второе правило использует элемент <AssignVariable>, чтобы считать значения и создать три новые переменные:

<!-- Policy #2: Get variables from the request -->
<AssignMessage continueOnError="false" enabled="true" name="get-variables">
  <AssignTo createNew="false" transport="http" type="request"/>
  <!-- Get the value of myAppSecret and create a new variable, secret -->
  <AssignVariable>
    <Name>secret</Name>
    <Ref>myAppSecret</Ref>
    <Value>0</Value>
  </AssignVariable>
  <!-- Get the value of config.environment and create a new variable, environment -->
  <AssignVariable>
    <Name>environment</Name>
    <Ref>config.environment</Ref>
    <Value>default</Value>
  </AssignVariable>
  <!-- Get the value of config.protocol and create a new variable, protocol -->
  <AssignVariable>
    <Name>protocol</Name>
    <Ref>config.protocol</Ref>
    <Value>default</Value>
  </AssignVariable>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Во втором правиле элемент <Ref> ссылается на исходную переменную, а элементы <Name> указывают названия новых переменных. Если переменная, на которую ссылается элемент <Ref>, недоступна, можно использовать значение, указанное в элементе <Value>.

Чтобы протестировать этот набор правил:

  1. Добавьте правила 1 и 2 в поток запросов. Правило 1 должно быть выше правила 2.
  2. Добавьте третье правило в поток response.
  3. Третье правило использует элемент <Set>, чтобы добавить переменные в ответ. В следующем примере создается полезная нагрузка XML в ответе, который Edge возвращает клиенту: 
    <!-- Policy #3: Add variables to the response -->
<AssignMessage continueOnError="false" enabled="true" name="put-em-in-the-payload">
  <DisplayName>put-em-in-the-payload</DisplayName>
  <Set>
    <Payload contentType="application/xml">
      <wrapper>
        <secret>{secret}</secret>
        <config>
          <environment>{environment}</environment>
          <protocol>{protocol}</protocol>
        </config>
      </wrapper>
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

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

    Убедитесь, что для атрибута contentType элемента <Payload> задано значение application/xml.

  4. Отправьте запрос к прокси-серверу API, например: 
    curl -vL https://ahamilton-eval-test.apigee.net/myproxy

    При желании вы можете передать результаты в утилиту, например xmllint, чтобы XML-код отображался в удобном формате:

    curl -vL https://ahamilton-eval-test.apigee.net/myproxy | xmllint --format -

    Тело ответа должно выглядеть следующим образом:

    <wrapper>
  <secret>42</secret>
  <config>
    <environment>test</environment>
    <protocol>gopher</protocol>
  </config>
</wrapper>

7. Получение заголовков ответа Service Callout

В примере ниже в запросе прокси-сервера API используется правило ServiceCallout, а ответ вызова содержит несколько заголовков с одинаковым названием (Set-Cookie). Если переменная ответа вызова сервиса имеет значение по умолчанию calloutResponse, то следующее правило получает второе значение заголовка Set-Cookie.

<AssignMessage name="AM-Payload-from-SC-header">
  <Set>
    <Payload contentType="application/json">
      {"Cookies from Service Callout":" {calloutResponse.header.Set-Cookie.2}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
  <AssignTo>response</AssignTo>
</AssignMessage>

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

{calloutResponse.header.Set-Cookie.values}

Для каждого дочернего элемента в этом справочнике приведены дополнительные примеры. Дополнительные примеры можно найти в примере AssignMessage на GitHub.

Ссылка на дочерний элемент

В этом разделе описываются дочерние элементы <AssignMessage>.

<Add>

Добавляет в запрос или ответ информацию, указанную в элементе <AssignTo>.

Элемент <Add> добавляет в письмо новые свойства, которых не было в исходном письме. Чтобы изменить значения существующих свойств, используйте элемент <Set>.

Значение по умолчанию –
Обязательно? Необязательно
Тип Сложный тип
Родительский элемент <AssignMessage>
Дочерние элементы <FormParams>
<Headers>
<QueryParams>

Элемент <Add> использует следующий синтаксис:

Синтаксисs1 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

Пример 1s2

В следующем примере элемент <FormParams> используется для получения значений трех параметров строки запроса из исходного запроса и их установки в качестве параметров формы в запросе целевой конечной точки:

<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 2s3

В следующем примере элемент <Headers> используется для добавления заголовка partner-id в запрос, который будет отправлен целевой конечной точке:

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 3s4

В следующем примере элемент <QueryParams> используется для добавления в запрос одного параметра запроса со статическим значением:

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

В этом примере используется <Add> в предварительном потоке запроса. Если вы посмотрите на результаты в таком инструменте, как Trace tool, то увидите, что запрос к https://example-target.com/get превращается в https://example-target.com/get?myParam=42.

Дочерние элементы <Add> поддерживают динамическую замену строк, которая называется шаблонами сообщений.

<FormParams> (дочерний элемент <Add>)

Добавляет новые параметры формы в сообщение запроса. Этот элемент не влияет на ответное сообщение.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <FormParam>
Родительский элемент <Add>
Дочерние элементы <FormParam>

Элемент <FormParams> использует следующий синтаксис:

Синтаксисs5 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
  </Add>
</AssignMessage>

Пример 1s6

В следующем примере в запрос добавляется один параметр формы ("answer") и статическое значение ("42"):

<AssignMessage name="AM-add-formparams-1">
  <Add>
    <FormParams>
      <FormParam name="answer">42</FormParam>
    </FormParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 2s7

В следующем примере показано, как получить значение параметра запроса name, добавить его в запрос в качестве параметра формы, а затем удалить параметр запроса:

<AssignMessage name="AM-Swap-QueryParam-to-FormParams">
  <Add>
    <FormParam name="name">{request.queryparam.name}</FormParam>
  </Add>
  <Remove>
    <QueryParam name="name"/>
  </Remove>
</AssignMessage>

Обратите внимание, что в этом примере не указана цель с помощью <AssignTo>. Это правило только добавляет параметр в запрос.

Пример 3s8

В примере ниже в запрос добавляется несколько параметров формы:

<AssignMessage name="AM-add-formparams-3">
  <Add>
    <FormParams>
      <FormParam name="username">{request.queryparam.name}</FormParam>
      <FormParam name="zip_code">{request.queryparam.zipCode}</FormParam>
      <FormParam name="default_language">{request.queryparam.lang}</FormParam>
    </FormParams>
  </Add>
  <Remove>
    <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

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

Для просмотра потока можно использовать инструмент Trace. Вы увидите, что тело запроса содержит данные формы в URL-кодировке, которые изначально были переданы в качестве параметров строки запроса:

username=nick&zip_code=90210&default_language=en

Вы можете использовать <FormParams>, только если выполняются следующие условия:

  • HTTP-метод: POST
  • Тип сообщения: запрос
  • Один или оба из следующих вариантов:
    • Данные формы: задайте значение или оставьте поле пустым. Например, если выбрана подсказка curl, то в запросе должно быть такое сочетание символов: -d "".
    • Заголовок Content-Length: установите значение 0 (если в исходном запросе нет данных; в противном случае укажите текущую длину в байтах). Например, если вы используете curl, добавьте в запрос -H "Content-Length: 0".

Пример:

curl -vL -X POST -d "" -H "Content-Type: application/x-www-form-urlencoded"
  https://ahamilton-eval-test.apigee.net/am-test

При добавлении <FormParams> Edge устанавливает для заголовка Content-Type запроса значение application/x-www-form-urlencoded перед отправкой сообщения в целевой сервис.

<Headers> (дочерний элемент <Add>)

Добавляет новые заголовки в указанный запрос или ответ, который задается элементом <AssignTo>.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <Header>
Родительский элемент <Add>
Дочерние элементы <Header>

Элемент <Headers> использует следующий синтаксис:

Синтаксисs9 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Add>
</AssignMessage>

Пример 1s10

В следующем примере в сообщение запроса добавляется заголовок partner-id, которому присваивается значение переменной потока verifyapikey.VAK-1.developer.app.partner-id.

<AssignMessage name="AM-add-headers-1">
  <Add>
    <Headers>
      <Header name="partner-id">{verifyapikey.VAK-1.developer.app.partner-id}</Header>
    </Headers>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

<QueryParams> (дочерний элемент <Add>)

Добавляет в запрос новые параметры. Этот элемент не влияет на ответ.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <QueryParam>
Родительский элемент <Add>
Дочерние элементы <QueryParam>

Элемент <QueryParams> использует следующий синтаксис:

Синтаксисs11 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Add>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Add>
</AssignMessage>

Пример 1s12

В следующем примере в запрос добавляется параметр запроса "myParam" со значением "42":

<AssignMessage name="AM-add-queryparams-1">
  <Add>
    <QueryParams>
      <QueryParam name="myParam">42</QueryParam>
    </QueryParams>
  </Add>
  <AssignTo>request</AssignTo>
</AssignMessage>

Вы можете использовать <QueryParams>, только если выполняются следующие условия:

  • HTTP-метод: GET
  • Тип сообщения: запрос

Кроме того, параметры запроса можно задавать, только если атрибут type элемента <AssignTo> является сообщением запроса. Если задать их в ответе, это ни на что не повлияет.

Если вы определите пустой массив параметров запроса в правиле (<Add><QueryParams/></Add>), правило не добавит никаких параметров запроса. Это то же самое, что не указывать <QueryParams>.

<AssignTo>

Определяет, с каким объектом работает правило AssignMessage. Доступны следующие варианты:

  • Сообщение запроса. request, полученный прокси-сервером API.
  • Ответное сообщение. response, возвращенный целевым сервером.
  • Специальное сообщение. Специальный объект запроса или ответа.

Обратите внимание, что в некоторых случаях вы не можете изменить объект, на который действует правило AssignMessage. Например, вы не можете использовать <Add> или <Set>, чтобы добавить или изменить параметры запроса (<QueryParams>) или формы (<FormParams>) в ответе. В запросе можно изменять только параметры запроса и формы.

Значение по умолчанию –
Обязательно? Необязательно
Тип Строка
Родительский элемент <AssignMessage>
Дочерние элементы Нет

Если вы не укажете <AssignTo> или укажете элемент <AssignTo>, но не укажете для него текстовое значение, правило будет действовать на запрос или ответ по умолчанию, в зависимости от того, где выполняется правило. Если правило выполняется в потоке запросов, оно влияет на сообщение запроса. Если правило выполняется в потоке ответа, оно по умолчанию влияет на ответ.

Элемент <AssignTo> использует следующий синтаксис:

Синтаксисs13 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
</AssignMessage>

Пример 1s14

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

<AssignMessage name="assignto-1">
<!-- DO NOT do this -->
  <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Пример 2s15

В следующем примере создается новый объект запроса:

<AssignMessage name="AM-assignto-2"> 
  <AssignTo createNew="true" transport="http" type="request">NameOfNewMessage</AssignTo> 
</AssignMessage>

Когда вы создаете новый объект запроса или ответа, другие элементы правила AssignMessage (такие как <Add>, <Set> и <Copy>) воздействуют на этот новый объект запроса.

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

Пример 3s16

В примере ниже создается объект запроса с названием MyRequestObject:

<AssignMessage name="assignto-2">
  <AssignTo createNew="true" transport="http" type="request"&gt;MyRequestObject&lt;/AssignTo>
</AssignMessage>

Когда вы создаете новый объект запроса или ответа, другие элементы правила AssignMessage (такие как <Add>, <Set> и <Copy>) воздействуют на этот новый объект запроса.

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

В таблице ниже описаны атрибуты <AssignTo>.

Атрибут Описание Обязательно? Тип
createNew

Определяет, создается ли новое сообщение при назначении значений.

Если задано значение true, правило создает новую переменную типа, указанного в type (request или response). Если вы не укажете название новой переменной, правило создаст новый объект запроса или ответа на основе значения type.

Если значение false, то политика реагирует одним из двух способов:

  • Если <AssignTo> может разрешить имя переменной в запрос или ответ, то обработка продолжается. Например, если правило находится в потоке запросов, переменная является объектом запроса. Если правило находится в ответе, переменная является объектом ответа.
  • Если <AssignTo> не удается разрешить или разрешается в тип, отличный от сообщения, правило выдает ошибку.

Если правило createNew не задано, то:

  • Если текстовое значение <AssignTo> разрешается в сообщение, обработка переходит к следующему шагу.
  • Если текстовое значение <AssignTo> не удается разрешить или оно разрешается в тип, отличный от сообщения, создается новая переменная типа, указанного в type.
 Необязательно Логическое значение
transport

Указывает тип транспорта для типа сообщения запроса или ответа.

Значение по умолчанию – http (единственное допустимое значение).

 Необязательно Строка
type Указывает тип нового сообщения, если createNew имеет значение true. Допустимые значения: request или response.

Если вы опустите этот атрибут, Edge создаст запрос или ответ в зависимости от того, где в потоке выполняется это правило.

 Необязательно Строка

<AssignVariable>

Присваивает значение переменной потока. Если переменная потока не существует, <AssignVariable> создает ее.

Значение по умолчанию –
Обязательно? Необязательно
Тип Сложный тип
Родительский элемент <AssignMessage>
Дочерние элементы <Name> (обязательно)
<Ref>
<Template>
<Value>

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

  • Строковый литерал. Используйте дочерний элемент <Value>, чтобы указать значение строкового литерала для переменной потока.
  • Переменная потока. Используйте дочерний элемент <Ref>, чтобы указать значение существующей переменной потока для целевой переменной потока. Полный список переменных потока, которые можно использовать в качестве источника, приведен в справочнике по переменным потока.
  • Шаблон сообщения. Используйте дочерний элемент <Template>, чтобы указать шаблон сообщения для интерполяции и получить значение, которое будет помещено в переменную целевого потока.

Элемент <AssignVariable> использует следующий синтаксис:

Синтаксисs17 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>

Используйте элемент <Ref>, чтобы указать исходную переменную. Если переменная, на которую ссылается <Ref>, недоступна, Edge использует значение, указанное элементом <Value>. Если вы зададите элемент <Template>, он будет иметь приоритет над другими дочерними элементами.

Пример 1s18

В следующем примере значение новой переменной myvar задается как литеральное значение "42":

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

Пример 2s19

В следующем примере значение переменной потока request.header.user-agent присваивается целевой переменной потока myvar, а значение параметра запроса country – целевой переменной потока Country:

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

Если одно из назначений не удается, Edge присваивает переменной целевого потока значение ErrorOnCopy.

Если переменные потока myvar или Country не существуют, <AssignVariable> создает их.

Пример 3s20

В следующем примере дочерний элемент <Template> используется для объединения двух контекстных переменных с помощью дефиса:

<AssignMessage name='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

Обычно <AssignVariable> используется для установки значения по умолчанию для параметра запроса, заголовка или другого значения, которое может быть передано вместе с запросом. Для этого используются дочерние элементы <Ref> и <Value>. Дополнительную информацию вы найдете в примерах для <Ref>.

<Name> (дочерний элемент <AssignVariable>)

Указывает название переменной целевого потока (например, переменной, значение которой задается правилом AssignMessage). Если переменной с именем, указанным в <AssignVariable>, не существует, правило создаст ее.

Значение по умолчанию –
Обязательно? Обязательно
Тип Строка
Родительский элемент <AssignVariable>
Дочерние элементы Нет

Элемент <Name> использует следующий синтаксис:

Синтаксисs21 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
  </AssignVariable>
</AssignMessage>

Пример 1s22

В следующем примере в качестве целевой переменной указана myvar, а в качестве ее значения – литеральное значение "42":

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

Если myvar не существует, <AssignVariable> создаст его.

<Ref> (дочерний элемент <AssignVariable>)

Указывает источник назначения в качестве переменной потока. Переменная потока может быть одной из стандартных переменных потока (перечисленных в справочнике по переменным потока) или созданной вами пользовательской переменной потока.

Значение <Ref> всегда интерпретируется как переменная потока. Вы не можете указать в качестве значения строковый литерал. Чтобы назначить строковое значение, используйте элемент <Value>.

Значение по умолчанию –
Обязательно? Необязательно
Тип Строка
Родительский элемент <AssignVariable>
Дочерние элементы Нет

При указании переменной потока с помощью <Ref> опустите фигурные скобки {}, которые обычно используются для ссылки на переменную потока. Например, чтобы присвоить новой переменной значение переменной потока client.host, выполните следующие действия:

Do this (no brackets):
  <Ref>client.host</Ref>

Do NOT do this (brackets):
  <Ref>{client.host}</Ref>

Чтобы задать значение по умолчанию для переменной целевого потока, используйте <Value> в сочетании с <Ref>. Если переменная потока, указанная в <Ref>, не существует, не может быть прочитана или имеет значение null, Edge присваивает целевой переменной потока значение <Value>.

Элемент <Ref> использует следующий синтаксис:

Синтаксис

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Ref>source_variable</Ref>
  </AssignVariable>
</AssignMessage>

Пример 1s23

В следующем примере значение переменной потока request.header.user-agent присваивается переменной целевого потока myvar, а значение параметра запроса country – переменной Country:

<AssignMessage name="assignvariable-4">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

В этом примере для Edge не указано значение по умолчанию (или резервное значение) ни для одного из назначений.

Пример 2s23

В следующем примере значение переменной потока request.header.user-agent присваивается переменной целевого потока myvar, а значение параметра запроса country – переменной Country:

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

В этом примере, если значения переменной потока request.header.user-agent или параметра запроса Country равны null, нечитаемы или имеют неправильный формат, Edge присваивает новым переменным значение ErrorOnCopy.

Пример 3s24

Чаще всего <AssignVariable> используется для того, чтобы задать значение по умолчанию для параметра запроса, заголовка или другого значения, которое может быть передано вместе с запросом. Например, вы создаете прокси-сервер API погоды, в котором запрос принимает один параметр запроса с именем "w". Этот параметр содержит идентификатор города, для которого вы хотите получить прогноз погоды. URL запроса имеет следующий вид:

http://myCO.com/v1/weather/forecastrss?w=city_ID

Чтобы задать значение по умолчанию для переменной w, создайте правило AssignMessage, как показано ниже.

<AssignMessage continueOnError="false" enabled="true" name="assignvariable-3">
  <AssignTo createNew="false" transport="http" type="request"/>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>request.queryparam.w</Name>
    <Ref>request.queryparam.w</Ref>
    <Value>12797282</Value>
  </AssignVariable>
</AssignMessage>

В этом примере <AssignVariable> получает значение request.queryparam.w и присваивает его себе. Если переменная потока имеет значение null, то есть параметр запроса w был опущен, то в этом примере используется значение по умолчанию из элемента <Value>. Поэтому вы можете отправить запрос к этому прокси-серверу API, опустив параметр запроса "w":

http://myCO.com/v1/weather/forecastrss

…и при этом прокси-сервер API возвращает действительный результат.

В отличие от <Value>, значением <Ref> должна быть переменная потока, например свойство объекта request, response или target. Значением также может быть созданная вами переменная пользовательского потока.

Если вы укажете переменную потока, которая не существует для значения <Ref>, а значение <IgnoreUnresolvedVariables> – true, Edge выдаст ошибку.

<Template> (дочерний элемент <AssignVariable>)

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

Используйте атрибут ref, чтобы указать переменную потока, значение которой является шаблоном сообщения. Например, вы можете сохранить шаблон сообщения как настраиваемый атрибут в приложении разработчика. Когда Edge идентифицирует приложение разработчика после проверки ключа API или токена безопасности (с помощью дополнительного правила), элемент <AssignVariable> может использовать шаблон сообщения из настраиваемого атрибута приложения, который доступен как переменная потока из правила безопасности.

Значение по умолчанию –
Обязательно? Необязательно
Тип Строка
Родительский элемент <AssignVariable>
Дочерние элементы Нет

Элемент <Template> использует следующий синтаксис:

Синтаксис: s25. 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Template>message_template</Template>
    or
    <Template ref='template_variable'></Template>
  </AssignVariable>
</AssignMessage>

Пример 1s26

В следующем примере используется синтаксис шаблонов сообщений для объединения двух контекстных переменных с литеральной строкой (дефисом) между ними:

<AssignMessage name='AV-via-template-1'>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

Пример 2s27

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

<AssignMessage name='AV-via-template-indirectly'>  
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_template_variable'/>
  </AssignVariable>
</AssignMessage>

Пример 3s28

В следующем примере указаны переменная потока и текстовое значение. В этом случае, если значение переменной не равно null, оно используется в качестве шаблона. Если значение, на которое указывает ссылка, равно null, то в качестве шаблона используется текстовое значение (в данном случае {system.uuid}-{messageid}). Этот шаблон полезен, когда нужно переопределить значение, то есть в некоторых случаях заменить шаблон по умолчанию (текстовую часть) динамически заданными значениями. Например, условный оператор может получить значение из пары "ключ-значение" и присвоить его переменной, на которую указывает ссылка:

<AssignMessage name='AV-template-with-fallback'> 
 <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignVariable>
    <Name>my_destination_variable</Name>
    <Value>BADDBEEF</Value>
    <Template ref='my_variable'>{system.uuid}-{messageid}</Template>
  </AssignVariable>
</AssignMessage>

<Value> (дочерний элемент <AssignVariable>)

Определяет значение переменной целевого потока, заданной с помощью <AssignVariable>. Значение всегда интерпретируется как строковый литерал. Вы не можете использовать переменную потока в качестве значения, даже если заключите ее в фигурные скобки ({}). Чтобы использовать переменную потока, укажите <Ref>.

Значение по умолчанию –
Обязательно? Необязательно
Тип Строка
Родительский элемент <AssignVariable>
Дочерние элементы Нет

При использовании в сочетании с элементом <Ref> элемент <Value> действует как значение по умолчанию (или резервное значение). Если значение <Ref> не указано, не может быть определено или равно null, используется значение <Value>.

Элемент <Value> использует следующий синтаксис:

Синтаксисs29 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <AssignVariable>
    <Name>variable_name</Name>
    <Value>variable_value</Value>
  </AssignVariable>
</AssignMessage>

Пример 1

В следующем примере переменной потока назначения myvar присваивается литеральное значение "42":

<AssignMessage name="assignvariable-1">
  <AssignVariable>
    <Name>myvar</Name>
    <Value>42</Value>
  </AssignVariable>
</AssignMessage>

Пример 2

В следующем примере значение переменной потока request.header.user-agent присваивается переменной потока myvar, а значение параметра запроса country – переменной Country:

<AssignMessage name="assignvariable-2">
  <AssignVariable>
    <Name>myvar</Name>
    <Ref>request.header.user-agent</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
    <Value>ErrorOnCopy</Value>
  </AssignVariable>
</AssignMessage>

Если одно из назначений не удается, <AssignVariable> присваивает переменной целевого потока значение ErrorOnCopy.

<Copy>

Копирует значения из сообщения, указанного в атрибуте source, в сообщение, указанное в элементе <AssignTo>. Если вы не укажете цель с помощью <AssignTo>, то это правило скопирует значения в запрос или ответ в зависимости от того, где в потоке оно выполняется.

Значение по умолчанию –
Обязательно? Необязательно
Тип Строка
Родительский элемент <AssignMessage>
Дочерние элементы <FormParams>
<Headers>
<Path>
<Payload>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

Если вы не укажете дочерние элементы в элементе <Copy>, будут скопированы все части указанного исходного сообщения.

Элемент <Copy> использует следующий синтаксис:

Синтаксисs30 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
    <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>[false|true]</Path>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>[false|true]</ReasonPhrase>
    <StatusCode>[false|true]</StatusCode>
    <Verb>[false|true]</Verb>
    <Version>[false|true]</Version>
  </Copy>
  <!-- Used as the destination for the <Copy> values -->
  <AssignTo createNew="[true|false]" transport="http"
    type="[request|response]">destination_variable_name</AssignTo>
</AssignMessage>

Пример 1s31

В следующем примере копируется заголовок, три параметра формы, путь и все параметры запроса из сообщения request в новый пользовательский запрос с именем newRequest:

<AssignMessage name="AM-copy-1">
  <AssignTo createNew="true" transport="http" type="request">newRequest</AssignTo>
  <Copy source="request">
    <Headers>
      <Header name="Header_Name_1"/>
    </Headers>
    <FormParams>
      <FormParam name="Form_Param_Name_1"/>
      <FormParam name="Form_Param_Name_2"/>
      <FormParam name="Form_Param_Name_3"/>
    </FormParams>
    <Path>true</Path>
    <QueryParams/>
  </Copy>
</AssignMessage>

Поскольку элементы <Payload> и <Verb> отсутствуют, правило не копирует эти части сообщения.

Пример 2s32

В примере ниже сначала удаляется все содержимое существующего сообщения response, а затем в него копируются все значения из другого сообщения – secondResponse response.

<AssignMessage name='AM-Copy-Response'>
  <AssignTo createNew="false" transport="http" type="response">response</AssignTo>
  <!-- first remove any existing values -->
  <Remove/>
  <!-- then copy everything from the designated message -->
  <Copy source="secondResponse"/>
</AssignMessage>

У элемента <Copy> есть один атрибут:

Атрибут Описание Обязательно? Тип
source

Указывает исходный объект копии.

  • Если значение source не указано, по умолчанию используется message, которое принимает разные значения в зависимости от потока, в котором выполняется правило. Если правило выполняется в потоке запроса, переменная message ссылается на объект request. Если правило выполняется в потоке ответа, переменная message ссылается на объект response.
  • Если исходная переменная не может быть разрешена или разрешается в тип, отличный от сообщения, <Copy> не отвечает.
 Необязательно Строка

<FormParams> (дочерний элемент <Copy>)

Копирует параметры формы из запроса, указанного в атрибуте source элемента <Copy>, в запрос, указанный в элементе <AssignTo>. Этот элемент не влияет на ответ.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <FormParam> или пустой массив.
Родительский элемент <Copy>
Дочерние элементы <FormParam>

Элемент <FormParams> использует следующий синтаксис:

Синтаксисs33 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Copy>
</AssignMessage>

Пример 1s34

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

<AssignMessage name="copy-formparams-1">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName">Form param value 1</FormParam>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Пример 2s35

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

<AssignMessage name="copy-formparams-2">
  <Copy source="request">
    <FormParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Пример 3s36

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

<AssignMessage name="copy-formparams-3">
  <Copy source="request">
    <FormParams>
      <FormParam name="paramName1"/>
      <FormParam name="paramName2"/>
      <FormParam name="paramName3"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Пример: s37.

Если у нескольких параметров формы одинаковое название, используйте следующий синтаксис:

<AssignMessage name="copy-formparams-4">
  <Copy source="request">
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

В этом примере копируются f1, f2 и второе значение f3. Если у f3 только одно значение, оно не копируется.

Вы можете использовать <FormParams>, только если выполняются следующие условия:

  • HTTP-метод: POST
  • Тип сообщения: ответ
  • Один или оба из следующих вариантов:
    • Данные формы: задайте значение или оставьте поле пустым. Например, если выбрана подсказка curl, то в запросе должно быть такое сочетание символов: -d "".
    • Заголовок Content-Length. Установите значение 0 (если в исходном запросе нет данных; в противном случае укажите текущую длину). Например, если вы используете curl, добавьте в запрос -H "Content-Length: 0".

При копировании <FormParams> <Copy> задает для Content-Type сообщения значение application/x-www-form-urlencoded, а затем отправляет сообщение в целевой сервис.

<Headers> (дочерний элемент <Copy>)

Копирует HTTP-заголовки из сообщения запроса или ответа, указанного атрибутом source элемента <Copy>, в сообщение запроса или ответа, указанное элементом <AssignTo>.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <Header> или пустой массив.
Родительский элемент <Copy>
Дочерние элементы <Header>

Элемент <Headers> использует следующий синтаксис:

Синтаксисs38 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Copy>
</AssignMessage>

Пример 1s39

В следующем примере заголовок user-agent копируется из запроса в новый объект пользовательского запроса:

<AssignMessage name="copy-headers-1">
  <Copy source="request">
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Пример 2: s40

Чтобы скопировать все заголовки, используйте пустой элемент <Headers>, как показано в примере ниже.

<AssignMessage name="copy-headers-2">
  <Copy source="request">
    <Headers/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Пример 3s41

Если есть несколько заголовков с одинаковым названием, используйте следующий синтаксис:

<AssignMessage name="copy-headers-3">
  <Copy source="request">
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

В этом примере копируются значения h1, h2 и второе значение h3. Если у h3 только одно значение, оно не копируется.

<Path> (дочерний элемент <Copy>)

Определяет, нужно ли копировать путь из исходного запроса в целевой. Этот элемент не влияет на ответ.

Если задано значение true, это правило копирует путь из сообщения запроса, указанного атрибутом source элемента <Copy>, в сообщение запроса, указанное элементом <AssignTo>.

Значение по умолчанию False
Обязательно? Необязательно
Тип Логическое значение
Родительский элемент <Copy>
Дочерние элементы Нет

Элемент <Path> использует следующий синтаксис:

Синтаксис

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Path>[false|true]</Path>
  </Copy>
</AssignMessage>

Пример 1s42

В следующем примере показано, как правило AssignMessage копирует путь из исходного запроса в новый объект запроса:

<AssignMessage name="copy-path-1">
  <Copy source="request">
    <Path>true</Path>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Вы можете использовать <Path>, только если выполняются следующие условия:

  • Тип сообщения: запрос

<Payload> (дочерний элемент <Copy>)

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

Если задано значение true, это правило копирует полезную нагрузку из сообщения, указанного в атрибуте source элемента <Copy>, в сообщение, указанное в элементе <AssignTo>.

Значение по умолчанию False
Обязательно? Необязательно
Тип Логическое значение
Родительский элемент <Copy>
Дочерние элементы Нет

Элемент <Payload> использует следующий синтаксис:

Синтаксисs43 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Payload>[false|true]</Payload>
  </Copy>
</AssignMessage>

Пример 1s44

В следующем примере для <Payload> задано значение true, чтобы полезная нагрузка запроса копировалась из запроса в ответ:

<AssignMessage name="AM-copy-payload-1">
  <Copy source="request">
    <Payload>true</Payload>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>

<QueryParams> (дочерний элемент <Copy>)

Копирует параметры строки запроса из запроса, указанного атрибутом source элемента <Copy>, в запрос, указанный элементом <AssignTo>. Этот элемент не влияет на ответ.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <QueryParam> или пустой массив.
Родительский элемент <QueryParam>
Дочерние элементы Нет

Элемент <QueryParams> использует следующий синтаксис:

Синтаксисs45 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Copy>
</AssignMessage>

Пример 1s46

В следующем примере параметр запроса my_param копируется из запроса в новый объект специального запроса:

<AssignMessage name="copy-queryparams-1">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="my_param"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Пример 2s47

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

<AssignMessage name="copy-queryparams-2">
  <Copy source="request">
    <QueryParams/>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Пример 3s48

Если у вас несколько параметров запроса с одинаковым названием, используйте следующий синтаксис:

<AssignMessage name="copy-queryparams-3">
  <Copy source="request">
    <QueryParams>
      <QueryParam name="qp1"/>
      <QueryParam name="qp2"/>
      <QueryParam name="qp3.2"/>
    </QueryParams>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

В этом примере копируются параметры qp1, qp2 и второе значение параметра qp3. Если у qp3 только одно значение, оно не копируется.

Вы можете использовать <QueryParams>, только если выполняются следующие условия:

  • HTTP-метод: GET
  • Тип сообщения: запрос

<ReasonPhrase> (дочерний элемент <Copy>)

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

Если задано значение True, это правило копирует ReasonPhrase из ответа, указанного атрибутом source элемента <Copy>, в ответ, указанный элементом <AssignTo>.

Значение по умолчанию False
Обязательно? Необязательно
Тип Логическое значение
Родительский элемент <Copy>
Дочерние элементы Нет

Элемент <ReasonPhrase> использует следующий синтаксис:

Синтаксисs49 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <ReasonPhrase>[false|true]</ReasonPhrase>
  </Copy>
</AssignMessage>

Пример 1s50

В приведенном ниже примере для параметра <ReasonPhrase> устанавливается значение true. При указанных источнике и элементе <AssignTo> <Copy> копирует пояснение из указанного ответного сообщения в объект response:

<AssignMessage name="AM-copy-reasonphrase-1">
  <Copy source="serviceCalloutResponse">
    <ReasonPhrase>true</ReasonPhrase>
  </Copy>
  <AssignTo>response</AssignTo>
</AssignMessage>

Вы можете использовать <ReasonPhrase>, только если исходное и целевое сообщения имеют тип Response.

<StatusCode> (дочерний элемент <Copy>)

Определяет, копируется ли код статуса из исходного ответа в целевой. Этот элемент не влияет на запрос.

Если задано значение true, это правило копирует код статуса из сообщения ответа, указанного атрибутом source элемента <Copy>, в сообщение ответа, указанное элементом <AssignTo>.

Значение по умолчанию False
Обязательно? Необязательно
Тип Логическое значение
Родительский элемент <Copy>
Дочерние элементы Нет

Элемент <StatusCode> использует следующий синтаксис:

Синтаксисs52 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <StatusCode>[false|true]</StatusCode>
  </Copy>
</AssignMessage>

Пример 1s53

В следующем примере для параметра <StatusCode> задано значение true, что позволяет скопировать код статуса из объекта ответа по умолчанию в новый объект ответа:

<AssignMessage name="copy-statuscode-1">
  <Copy source="response">
    <StatusCode>true</StatusCode>
  </Copy>
  <AssignTo createNew="true" transport="http" type="response">MyCustomResponse</AssignTo>
</AssignMessage>

Вы можете использовать <StatusCode>, только если исходное и целевое сообщения имеют тип Response.

Часто <StatusCode> используется для того, чтобы задать для кода статуса ответа прокси-сервера значение, отличное от полученного от целевого сервера.

<Verb> (дочерний элемент <Copy>)

Определяет, копируется ли HTTP-глагол из исходного запроса в целевой. Этот элемент не влияет на ответ.

Если задано значение true, копирует глагол, найденный в атрибуте source элемента <Copy>, в запрос, указанный в элементе <AssignTo>.

Значение по умолчанию False
Обязательно? Необязательно
Тип Логическое значение
Родительский элемент <Copy>
Дочерние элементы Нет

Элемент <Verb> использует следующий синтаксис:

Синтаксисs54 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Verb>[false|true]</Verb>
  </Copy>
</AssignMessage>

Пример 1s55

В примере ниже для параметра <Verb> задано значение true, поэтому глагол из запроса по умолчанию копируется в новый специальный запрос.

<AssignMessage name="copy-verb-1">
  <Copy source="request">
    <Verb>true</Verb>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Вы можете использовать <Verb>, только если выполняются следующие условия:

  • Тип сообщения: запрос

<Version> (дочерний элемент <Copy>)

Определяет, копируется ли версия HTTP из исходного запроса в целевой. Этот элемент не влияет на ответ.

Если задано значение true, копирует версию HTTP, найденную в атрибуте source элемента <Copy>, в объект, указанный элементом <AssignTo>.

Значение по умолчанию False
Обязательно? Необязательно
Тип Логическое значение
Родительский элемент <Copy>
Дочерние элементы Нет

Элемент <Version> использует следующий синтаксис:

Синтаксисs56 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Copy source="[request|response]">
    <Version>[false|true]</Version>
  </Copy>
</AssignMessage>

Пример 1s57

В следующем примере для параметра <Version> в запросе задано значение true, что позволяет скопировать версию из объекта запроса по умолчанию в новый объект пользовательского запроса:

<AssignMessage name="copy-version-1">
  <Copy source="request">
    <Version>true</Version>
  </Copy>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Вы можете использовать <Version>, только если выполняются следующие условия:

  • Тип сообщения: запрос

<DisplayName>

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

Элемент <DisplayName> является общим для всех правил.

Значение по умолчанию –
Обязательно? Необязательное поле. Если вы не укажете <DisplayName>, будет использоваться значение атрибута name правила.
Тип Строка
Родительский элемент <PolicyElement>
Дочерние элементы Нет

Элемент <DisplayName> использует следующий синтаксис:

Синтаксис

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

Пример

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

У элемента <DisplayName> нет атрибутов или дочерних элементов.

<IgnoreUnresolvedVariables>

Определяет, прекращается ли обработка при обнаружении неразрешенной переменной.

Значение по умолчанию False
Обязательно? Необязательно
Тип Логическое значение
Родительский элемент <AssignMessage>
Дочерние элементы Нет

Установите значение true, чтобы игнорировать неразрешенные переменные и продолжить обработку. В противном случае установите значение false. Значение по умолчанию: false.

Задание значения true для <IgnoreUnresolvedVariables> отличается от задания значения true для continueOnError в <AssignMessage> тем, что оно относится к заданию и получению значений переменных. Если задать для continueOnError значение true, Edge будет игнорировать все ошибки, а не только те, которые возникают при использовании переменных.

Элемент <IgnoreUnresolvedVariables> использует следующий синтаксис:

Синтаксисs58 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <IgnoreUnresolvedVariables>[true|false]
  </IgnoreUnresolvedVariables>
</AssignMessage>

Пример 1s59

В примере ниже для параметра <IgnoreUnresolvedVariables> задано значение true.

<AssignMessage name="AM-Set-Headers">
  <Set>
    <Headers>
      <Header name='new-header'>{possibly-defined-variable}<Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true
  </IgnoreUnresolvedVariables>
</AssignMessage>

Поскольку для <IgnoreUnresolvedVariables> задано значение true, если переменная possibly-defined-variable не определена, это правило не приведет к ошибке.

<Remove>

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

Значение по умолчанию –
Обязательно? Необязательно
Тип Сложный тип
Родительский элемент <AssignMessage>
Дочерние элементы <FormParams>
<Headers>
<Payload>
<QueryParams>

Чаще всего <Remove> используется для удаления параметра запроса или заголовка, содержащего конфиденциальную информацию, из объекта входящего запроса, чтобы не передавать ее на бэкенд-сервер.

Элемент <Remove> использует следующий синтаксис:

Синтаксисs60 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Payload>[false|true]</Payload>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

Пример 1s61

В следующем примере из ответа удаляется тело сообщения:

<AssignMessage name="AM-remove-1">
  <DisplayName>remove-1</DisplayName>
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>response</AssignTo>
</AssignMessage>

В потоке ответов это правило удаляет тело ответа, возвращая клиенту только HTTP-заголовки.

Пример 2s62

В следующем примере из объекта request удаляются все параметры формы и параметр запроса:

<AssignMessage name="AM-remove-2">
  <Remove>
    <!-- Empty (<FormParams/>) removes all form parameters -->
    <FormParams/>
    <QueryParams>
      <QueryParam name="qp1"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 3s63

В следующем примере из объекта сообщения удаляется все:

<AssignMessage name="AM-remove-3">
  <Remove/>
  <AssignTo>request</AssignTo>
</AssignMessage>

Обычно это делается только в том случае, если вы собираетесь использовать элемент <Set> или <Copy>, чтобы задать в сообщении значения для замены.

<FormParams> (дочерний элемент <Remove>)

Удаляет из запроса указанные параметры формы. Этот элемент не влияет на ответ.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <FormParam> или пустой массив.
Родительский элемент <Remove>
Дочерние элементы <FormParam>

Элемент <FormParams> использует следующий синтаксис:

Синтаксис: s64 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<FormParams/>) -->
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Remove>
</AssignMessage>

Пример 1s65

В следующем примере из запроса удаляются три параметра формы:

<AssignMessage name="AM-remove-formparams-1">
  <Remove>
    <FormParams>
      <FormParam name="form_param_1"/>
      <FormParam name="form_param_2"/>
      <FormParam name="form_param_3"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 2s66

В следующем примере из запроса удаляются все параметры формы:

<AssignMessage name="AM-remove-formparams-2">
  <Remove>
    <FormParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 3s67

Если у нескольких параметров формы одинаковое название, используйте следующий синтаксис:

<AssignMessage name="AM-remove-formparams-3">
  <Remove>
    <FormParams>
      <FormParam name="f1"/>
      <FormParam name="f2"/>
      <FormParam name="f3.2"/>
    </FormParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

В этом примере удаляются значения f1, f2 и второе значение f3. Если у f3 только одно значение, оно не удаляется.

Вы можете использовать <FormParams>, только если выполняются следующие условия:

  • Тип сообщения: запрос
  • Content-Type: "application/x-www-form-urlencoded"

<Headers> (дочерний элемент <Remove>)

Удаляет указанные HTTP-заголовки из запроса или ответа, заданного элементом <AssignTo>.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <Header> или пустой массив.
Родительский элемент <Remove>
Дочерние элементы <Header>

Элемент <Headers> использует следующий синтаксис:

Синтаксис

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<Headers/>) -->
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Remove>
</AssignMessage>

Пример 1s68

В примере ниже из запроса удаляется заголовок user-agent:

<AssignMessage name="AM-remove-one-header">
  <Remove>
    <Headers>
      <Header name="user-agent"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 2s69

В следующем примере из запроса удаляются все заголовки:

<AssignMessage name="AM-remove-all-headers">
  <Remove>
    <Headers/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 3s70

Если есть несколько заголовков с одинаковым названием, используйте следующий синтаксис:

<AssignMessage name="AM-remove-headers-3">
  <Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

В этом примере из запроса удаляются заголовки h1, h2 и второе значение заголовка h3. Если у h3 только одно значение, оно не удаляется.

<Payload> (дочерний элемент <Remove>)

Определяет, удаляет ли <Remove> полезную нагрузку в запросе или ответе, которая указана элементом <AssignTo>. Чтобы очистить полезную нагрузку, задайте значение true, в противном случае – false. Значение по умолчанию – false.

Значение по умолчанию False
Обязательно? Необязательно
Тип Логическое значение
Родительский элемент <Remove>
Дочерние элементы Нет

Элемент <Payload> использует следующий синтаксис:

Синтаксис

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <Payload>[false|true]</Payload>
  </Remove>
</AssignMessage>

Пример 1s71

В приведенном ниже примере для параметра <Payload> устанавливается значение true, чтобы очистить полезную нагрузку запроса.

<AssignMessage name="AM-remove-payload-1">
  <Remove>
    <Payload>true</Payload>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

<QueryParams> (дочерний элемент <Remove>)

Удаляет из запроса указанные параметры. Этот элемент не влияет на ответ.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <QueryParam> или пустой массив.
Родительский элемент <Remove>
Дочерние элементы <QueryParam>

Элемент <QueryParams> использует следующий синтаксис:

Синтаксисs72 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Remove>
    <!-- Can also be an empty array (<QueryParams/>) -->
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Remove>
</AssignMessage>

Пример 1s73

В следующем примере из запроса удаляется один параметр запроса:

<AssignMessage name="AM-remove-queryparams-1">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 2s74

В следующем примере из запроса удаляются все параметры:

<AssignMessage name="AM-remove-queryparams-2">
  <Remove>
      <QueryParams/>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 3s75

Если у вас несколько параметров запроса с одинаковым названием, используйте следующий синтаксис:

<AssignMessage name="AM-remove-queryparams-3">
  <Remove>
      <QueryParams>
        <QueryParam name="qp1"/>
        <QueryParam name="qp2"/>
        <QueryParam name="qp3.2"/>
      </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

В этом примере из запроса удаляются параметры qp1, qp2 и второе значение параметра qp3. Если у параметра qp3 только одно значение, оно не удаляется.

Пример 4s76

В примере ниже из запроса удаляется параметр apikey:

<AssignMessage name="AM-remove-query-param">
  <Remove>
    <QueryParams>
      <QueryParam name="apikey"/>
    </QueryParams>
  </Remove>
  <AssignTo>request</AssignTo>
</AssignMessage>

Вы можете использовать <QueryParams>, только если соблюдены следующие условия:

  • HTTP-метод: GET
  • Тип сообщения: запрос

<Set>

Задает информацию в сообщении запроса или ответа, которая определяется элементом <AssignTo>. <Set> перезаписывает заголовки, запросы или параметры формы, которые уже есть в исходном сообщении. Заголовки, запросы и параметры формы в HTTP-сообщении могут содержать несколько значений. Чтобы добавить дополнительные значения для заголовка или параметра, используйте элемент <Add>.

Значение по умолчанию –
Обязательно? Необязательно
Тип Сложный тип
Родительский элемент <AssignMessage>
Дочерние элементы <FormParams>
<Headers>
<Payload>
<Path>
<QueryParams>
<ReasonPhrase>
<StatusCode>
<Verb>
<Version>

Элемент <Set> использует следующий синтаксис:

Синтаксис

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
    <Path>path</Path>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

Пример 1s77

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

<AssignMessage name="AM-Set-Header">
  <Set>
    <Headers>
        <Header name="authenticated-developer">{verifyapikey.VAK-1.developer.id}</Header>
    </Headers>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 2s78

В примере ниже перезаписывается полезная нагрузка для ответа, а также заголовок Content-Type.

<AssignMessage name="AM-Overwrite-Payload">
  <Set>
    <Payload contentType="application/json">{ "status" : 42 }</Payload>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

<FormParams> (дочерний элемент <Set>)

Перезаписывает существующие параметры формы в запросе и заменяет их новыми значениями, которые вы указываете в этом элементе. Этот элемент не влияет на ответ.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <FormParam>
Родительский элемент <Set>
Дочерние элементы <FormParam>

Элемент <FormParams> использует следующий синтаксис:

Синтаксисs79 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <FormParams>
      <FormParam name="formparam_name">formparam_value</FormParam>
      ...
    </FormParams>
  </Set>
</AssignMessage>

Пример 1s80

В следующем примере параметр формы "myparam" получает значение переменной request.header.myparam в новом специальном запросе:

<AssignMessage name="AM-set-formparams-1">
  <Set>
    <FormParams>
      <FormParam name="myparam">{request.header.myparam}</FormParam>
    </FormParams>
  </Set>
  <AssignTo createNew="true" transport="http" type="request">MyCustomRequest</AssignTo>
</AssignMessage>

Вы можете использовать <FormParams>, только если выполняются следующие условия:

  • HTTP-метод: POST
  • Тип сообщения: запрос

Если вы зададите в правиле пустые параметры формы (<Add><FormParams/></Add>), то правило не добавит никаких параметров. Это то же самое, что не указывать <FormParams>.

<Set> изменяет Content-Type сообщения на application/x-www-form-urlencoded перед отправкой в целевую конечную точку.

<Headers> (дочерний элемент <Set>)

Перезаписывает существующие HTTP-заголовки в запросе или ответе, которые указаны в элементе <AssignTo>.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <Header>
Родительский элемент <Set>
Дочерние элементы <Header>

Элемент <Headers> использует следующий синтаксис:

Синтаксисs81 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Headers>
      <Header name="header_name">header_value</Header>
      ...
    </Headers>
  </Set>
</AssignMessage>

Пример 1s81

В следующем примере заголовку x-ratelimit-remaining присваивается значение переменной ratelimit.Quota-1.available.count:

<AssignMessage name="AM-Set-RateLimit-Header">
  <Set>
    <Headers>
      <Header name="X-RateLimit-Remaining">{ratelimit.Quota-1.available.count}</Header>
    </Headers>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

Если вы определите пустые заголовки в правиле (<Set><Headers/></Set>), оно не будет задавать заголовки. Это приведет к тому же результату, что и отсутствие параметра <Headers>.

<Path> (дочерний элемент <Set>)

<Payload> (дочерний элемент <Set>)

Определяет тело сообщения для запроса или ответа, которое задается элементом <AssignTo>. Полезная нагрузка может быть любого допустимого типа, например обычный текст, JSON или XML.

Значение по умолчанию пустая строка
Обязательно? Необязательно
Тип Строка
Родительский элемент <Set>
Дочерние элементы Нет

Элемент <Payload> использует следующий синтаксис:

Синтаксисs82 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Payload contentType="content_type" variablePrefix="prefix"
        variableSuffix="suffix">new_payload</Payload>
  </Set>
</AssignMessage>

Пример 1s83

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

<AssignMessage name="set-payload-1">
  <Set>
    <Payload contentType="text/plain">42</Payload>
  </Set>
</AssignMessage>

Пример 2s84

В примере ниже показано, как задать полезную нагрузку JSON.

<AssignMessage name="set-payload-2">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"bar"}
    </Payload>
  </Set>
</AssignMessage>

Пример 3s85

В следующем примере значения переменных вставляются в полезную нагрузку путем заключения имен переменных в фигурные скобки:

<AssignMessage name="set-payload-3">
  <Set>
    <Payload contentType="application/json">
      {"name":"foo", "type":"{variable_name}"}
    </Payload>
  </Set>
</AssignMessage>

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

<AssignMessage name="set-payload-3b">
  <Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
      {"name":"foo", "type":"@variable_name#"}
    </Payload>
  </Set>
</AssignMessage>

Старый синтаксис по-прежнему работает.

Пример 4s86

Содержимое файла <Payload> обрабатывается как шаблон сообщения. Это означает, что правило AssignMessage заменяет переменные, заключенные в фигурные скобки, значением указанных переменных во время выполнения.

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

<AssignMessage name="set-payload-4">
  <Set>
    <Payload contentType="text/xml">
      <root>
        <e1>sunday</e1>
        <e2>funday</e2>
        <e3>{var1}</e3>
      </root>
    </Payload>
  </Set>
</AssignMessage>

В таблице ниже описаны атрибуты <Payload>.

Атрибут Описание Тип поля Тип
contentType

Если значение contentType указано, оно присваивается HTTP-заголовку Content-Type.

 Необязательно Строка
variablePrefix Необязательный параметр, который указывает начальный разделитель в переменной потока. По умолчанию используется значение "{". Подробную информацию можно найти в справочнике по переменным потока. Необязательно Угля
variableSuffix При необходимости указывает конечный разделитель в переменной потока. По умолчанию используется значение "}". Подробную информацию можно найти в справочнике по переменным потока. Необязательно Угля

<QueryParams> (дочерний элемент <Set>)

Заменяет существующие параметры запроса новыми значениями. Этот элемент не влияет на ответ.

Значение по умолчанию –
Обязательно? Необязательно
Тип Массив элементов <QueryParam>
Родительский элемент <Set>
Дочерние элементы <QueryParam>

Элемент <QueryParams> использует следующий синтаксис:

Синтаксисs87 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <QueryParams>
      <QueryParam name="queryparam_name">queryparam_value</QueryParam>
      ...
    </QueryParams>
  </Set>
</AssignMessage>

Пример 1s88

В следующем примере параметру запроса address присваивается значение переменной request.header.address:

<AssignMessage name="AM-set-queryparams-1">  <Set>
    <QueryParams>
      <QueryParam name="address">{request.header.address}</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

Вы можете использовать <QueryParams>, только если выполняются следующие условия:

  • HTTP-метод: GET
  • Тип сообщения: запрос

Если вы определите пустые параметры запроса в правиле (<Set><QueryParams/></Set>), правило не будет задавать никаких параметров запроса. Это то же самое, что не указывать <QueryParams>.

<ReasonPhrase> (дочерний элемент <Set>)

Задает фразу с причиной в ответе. Обычно это делается для отладки в сочетании с <StatusCode>. Этот элемент не влияет на запрос.

Значение по умолчанию –
Обязательно? Необязательно
Тип Строка
Родительский элемент <Set>
Дочерние элементы Нет

Элемент <ReasonPhrase> использует следующий синтаксис:

Синтаксисs89 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <ReasonPhrase>reason_for_error or {variable}</ReasonPhrase>
  </Set>
</AssignMessage>

Пример 1: s90

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

<AssignMessage name="set-reasonphrase-1">
  <Set>
    <ReasonPhrase>Bad medicine</ReasonPhrase>
  </Set>
  <AssignTo createNew="true" transport="http" type="response"/>
</AssignMessage>

Пример 2s91

Содержимое файла <ReasonPhrase> обрабатывается как шаблон сообщения. Это означает, что название переменной, заключенное в фигурные скобки, во время выполнения будет заменено значением указанной переменной, как показано в следующем примере:

<AssignMessage name="AM-set-reasonphrase-2">
  <Set>
    <ReasonPhrase>{calloutresponse.reason.phrase}</ReasonPhrase>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

Вы можете использовать <ReasonPhrase>, только если выполняются следующие условия:

  • Тип сообщения: ответ

<StatusCode> (дочерний элемент <Set>)

Задает код статуса ответа. Этот элемент не влияет на запрос.

Значение по умолчанию 200 (если атрибут createNew элемента <AssignTo> имеет значение true).
Обязательно? Необязательно
Тип Строка или variable
Родительский элемент <Set>
Дочерние элементы Нет

Элемент <StatusCode> использует следующий синтаксис:

Синтаксисs92 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <StatusCode>HTTP_status_code or {variable}</StatusCode>
  </Set>
</AssignMessage>

Пример 1

В следующем примере задается простой код статуса:

<AssignMessage name="AM-set-statuscode-404">
  <Set>
    <StatusCode>404</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

Пример 2

Содержимое файла <StatusCode> обрабатывается как шаблон сообщения. Это означает, что название переменной, заключенное в фигурные скобки, во время выполнения будет заменено значением указанной переменной, как показано в следующем примере:

<AssignMessage name="set-statuscode-2">
  <Set>
    <StatusCode>{calloutresponse.status.code}</StatusCode>
  </Set>
  <AssignTo>response</AssignTo>
</AssignMessage>

Вы можете использовать <StatusCode>, только если выполняются следующие условия:

  • Тип сообщения: ответ

<Verb> (дочерний элемент <Set>)

Задает HTTP-глагол в запросе. Этот элемент не влияет на ответ.

Значение по умолчанию –
Обязательно? Необязательно
Тип Строка или variable
Родительский элемент <Set>
Дочерние элементы Нет

Элемент <Verb> использует следующий синтаксис:

Синтаксис

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Verb>[GET|POST|PUT|PATCH|DELETE|{variable}]</Verb>
  </Set>
</AssignMessage>

Пример 1s93

В следующем примере в запросе задается простой глагол:

<AssignMessage name="AM-set-verb-1">
  <Set>
    <Verb>POST</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

Пример 2s94

Содержимое файла <Verb> обрабатывается как шаблон сообщения. Это означает, что название переменной, заключенное в фигурные скобки, во время выполнения будет заменено значением указанной переменной.

В следующем примере переменная используется для подстановки глагола:

<AssignMessage name="AM-set-verb-to-dynamic-value">
  <Set>
    <Verb>{my_variable}</Verb>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

Вы можете использовать <Verb>, только если выполняются следующие условия:

  • Тип сообщения: запрос

<Version> (дочерний элемент <Set>)

Задает версию HTTP в запросе. Этот элемент не влияет на ответ.

Значение по умолчанию –
Обязательно? Необязательно
Тип Строка или variable
Родительский элемент <Set>
Дочерние элементы Нет

Элемент <Version> использует следующий синтаксис:

Синтаксисs95 

<AssignMessage
    continueOnError="[false|true]"
    enabled="[true|false]"
    name="policy_name" >
  <Set>
    <Version>[1.0|1.1|{variable}]</Verb>
  </Set>
</AssignMessage>

Пример 1s96

В примере ниже номер версии – 1.1.

<AssignMessage name="AM-set-version-1">
  <Set>
    <Version>1.1</Version>
  </Set>
 </AssignMessage>

Пример 2

В следующем примере для указания номера версии используется переменная в фигурных скобках:

<AssignMessage name="AM-set-version-2">
  <Set>
    <Version>{my_version}</Version>
  </Set>
  <AssignTo>request</AssignTo>
</AssignMessage>

Содержимое файла <Version> обрабатывается как шаблон сообщения. Это означает, что название переменной, заключенное в фигурные скобки, во время выполнения будет заменено значением указанной переменной.

Вы можете использовать <Version>, только если выполняются следующие условия:

  • Тип сообщения: запрос

Как создавать собственные сообщения с запросом согласия

Вы можете использовать политику AssignMessage, чтобы создать специальное сообщение запроса. После создания специального запроса вы можете использовать его следующими способами:

  • Доступ к переменным в других правилах
  • Передать во внешний сервис.

Чтобы создать специальное сообщение запроса, используйте элемент <AssignTo> в правиле AssignMessage. Задайте для атрибута createNew значение true и укажите название нового сообщения в теле элемента, как показано в примере ниже.

<AssignMessage name="AM-assignto-2"> 
  <AssignTo createNew="true" transport="http" type="request">NameOfNewMessage</AssignTo> 
</AssignMessage>

По умолчанию Edge не выполняет никаких действий со специальным сообщением запроса. После создания Edge продолжит выполнение исходного запроса. Чтобы использовать специальный запрос, добавьте в прокси-сервер правило, например ServiceCallout, которое может передавать специальный запрос внешнему сервису.

Ниже приведены примеры создания специальных сообщений с запросом.

Пример 1s97

В следующем примере создается объект пользовательского запроса с помощью Assign Message:

<AssignMessage name="AssignMessage-3">
  <AssignTo createNew="true" type="request">MyCustomRequest</AssignTo>
  <Copy>
    <Headers>
     <Header name="user-agent"/>
    </Headers>
  </Copy>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.addy}</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <IgnoreUnresolvedVariables>false
  </IgnoreUnresolvedVariables>
</AssignMessage>

который:

  • Создает новый объект сообщения запроса с названием MyCustomRequest.
  • В MyCustomRequest это правило:
    • Копирует значение HTTP-заголовка user-agent из входящего запроса в новое сообщение. Поскольку <Copy> использует абсолютную ссылку на переменную потока user-agent, указывать атрибут source для <Copy> не нужно.
    • Задает для параметра запроса address в специальном сообщении значение параметра запроса addy во входящем запросе.
    • Задает для HTTP-команды значение GET.
  • Задает для <IgnoreUnresolvedVariables> значение false. Если для <IgnoreUnresolvedVariables> задано значение false, а одна из переменных, которую пытается добавить правило, не существует, Edge прекратит обработку в потоке API.

Пример 2s98

Вот ещё один пример, демонстрирующий, как создать объект пользовательского запроса с помощью Assign Message:

<AssignMessage name="AssignMessage-2">
  <AssignTo createNew="true" type="request">partner.request</AssignTo>
  <Set>
    <Verb>POST</Verb>
    <Payload contentType="text/xml">
      <request><operation>105</operation></request>
    </Payload>
  </Set>
</AssignMessage>

В этом примере создается новый специальный запрос с названием partner.request. Затем он задает <Verb> и <Payload> в новом запросе.

Вы можете получить доступ к специальному сообщению запроса в другом правиле AssignMessage, которое выполняется позже в потоке. В следующем примере показано, как получить значение заголовка user-agent специального сообщения запроса:

<AssignMessage name="custom-request-1-access">
  <DisplayName>custom-request-1-access</DisplayName>
  <AssignTo>partner.request</AssignTo>
  <Set>
    <Headers>
      <Header name="user-agentCopyCustomRequest">{MyCustomRequest.header.user-agent}</Header>
    </Headers>
  </Set>
</AssignMessage>

Видео

Чтобы узнать больше о правиле AssignMessage, посмотрите следующие видео.

Видео Описание
Зачем назначать правила для сообщений? Узнайте о преимуществах использования правила AssignMessage для изменения запроса или ответа API без изменения кода серверной части.
Как скопировать элементы API с помощью правила AssignMessage Скопируйте элементы из запроса к API или ответа и создайте новый объект запроса или ответа, используя правило AssignMessage.
Как удалить элементы API с помощью правила AssignMessage Удаляйте элементы API и изменяйте API до того, как он достигнет целевого бэкенда, с помощью правила AssignMessage.
Как добавлять и настраивать элементы API с помощью правила AssignMessage Изменение запроса к API или ответа путем добавления параметров запроса, заголовков, параметров формы или полезной нагрузки с помощью правила AssignMessage.
Как создать пользовательские переменные с помощью правила AssignMessage Задайте пользовательские переменные потока с помощью правила AssignMessage и используйте их в других правилах прокси-сервера API.
Создание новых объектов запроса или ответа с помощью правила AssignMessage Создавайте новые объекты запросов к API или ответов с помощью правила AssignMessage во время выполнения API.
Как создать макет API с помощью правила AssignMessage Создайте простой макет REST API, добавив политику AssignMessage в поток ответов.
Задайте или измените полезную нагрузку с помощью правила AssignMessage Преобразуйте REST-запрос в SOAP-запрос, задав полезную нагрузку SOAP с помощью правила AssignMessage во время выполнения API.

Коды ошибок

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

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

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

Код ошибки Статус HTTP Причина Исправить
steps.assignmessage.SetVariableFailed 500 Правило не смогло задать переменную. Название неразрешенной переменной можно найти в строке ошибки.
steps.assignmessage.VariableOfNonMsgType 500

Эта ошибка возникает, если атрибуту source элемента <Copy> присвоена переменная, которая не относится к типу message.

Переменные типа сообщения представляют собой полные HTTP-запросы и ответы. Встроенные переменные потока Edge request, response и message имеют тип message. Подробнее о переменных в сообщениях…
steps.assignmessage.UnresolvedVariable 500

Эта ошибка возникает, если переменная, указанная в правиле "Назначить сообщение",

  • недоступно (недоступно в определенном процессе, в котором выполняется правило).
    • или
  • не может быть разрешен (не определен);

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

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

Название ошибки Причина Исправить
InvalidIndex Если индекс, указанный в элементах <Copy> и/или <Remove> правила "Назначить сообщение", равен 0 или отрицательному числу, развертывание прокси API завершится неудачно.
InvalidVariableName Если дочерний элемент <Name> пуст или не указан в элементе <AssignVariable>, развертывание прокси-сервера API завершится неудачно, поскольку нет действительного имени переменной, которой можно присвоить значение. Укажите допустимое имя переменной.
InvalidPayload Недопустимая полезная нагрузка, указанная в правиле.

Переменные ошибок

Эти переменные задаются, когда правило вызывает ошибку во время выполнения. Подробнее о нарушениях правил…

Переменные Место Пример
fault.name="fault_name" fault_name – название ошибки, указанное в таблице Ошибки выполнения выше. Название ошибки – это последняя часть кода ошибки. fault.name Matches "UnresolvedVariable"
assignmessage.policy_name.failed policy_name – заданное пользователем название правила, которое вызвало ошибку. assignmessage.AM-SetResponse.failed = true

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

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.assignmessage.VariableOfNonMsgType"
      },
      "faultstring":"AssignMessage[AM-SetResponse]: value of variable is not of type Message"
   }
}

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

    <FaultRule name="Assign Message Faults">    <Step>
        <Name>AM-CustomNonMessageTypeErrorResponse</Name>
        <Condition>(fault.name Matches "VariableOfNonMsgType") </Condition>
    </Step>
    <Step>
        <Name>AM-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(assignmessage.failed = true) </Condition>
</FaultRule>

Схемы

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

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

Рабочие примеры правила AssignMessage доступны в примерах платформы API.

Более сложный пример переопределения target.url из ProxyEndpoint приведен в этой статье сообщества Apigee.

Чтобы посмотреть, как работает set path в правиле ServiceCallout, ознакомьтесь с примером в GitHub Apigee. Просто клонируйте репозиторий и следуйте инструкциям в этом разделе. В примере используется правило AssignMessage для настройки пути запроса, а затем правило Service Callout для отправки запроса внешнему сервису.