Правило KeyValueMapOperations

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

Что

Предоставляет доступ на основе правил к хранилищу карт "ключ-значение" (KVM), доступному в Apigee Edge. Пары "ключ-значение" можно хранить, извлекать и удалять из существующих именованных карт, настраивая правила KeyValueMapOperations, которые указывают операции PUT, GET или DELETE. (Правило должно выполнять хотя бы одну из этих операций.)

Видео

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

Примеры

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="FooKVM" mapIdentifier="FooKVM">
  <DisplayName>FooKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Put>
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
    <Value>foo</Value>
    <Value>bar</Value>
  </Put>
</KeyValueMapOperations>

<KeyValueMapOperations mapIdentifier="FooKVM" async="false" continueOnError="false" enabled="true" name="GetKVM">
  <DisplayName>GetKVM</DisplayName>
  <ExpiryTimeInSecs>86400</ExpiryTimeInSecs>
  <Scope>environment</Scope>
  <Get assignTo="foo_variable" index="2">
    <Key>
      <Parameter>FooKey_1</Parameter>
    </Key>
  </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="putUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Put override="true">
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
      <Value ref="urlencoding.longurl.encoded"/>
      <Value ref="request.queryparam.url"/>
   </Put>
</KeyValueMapOperations>

{
    "entry" :[
        {
            "name" : "ed24e12820f2f900ae383b7cc4f2b31c402db1be",
            "value" : "http://tinyurl.com/38lwmlr,http://apigee.com"
        }
    ],
    "name" : "urlMapper"
}

<KeyValueMapOperations name="getUrl" mapIdentifier="urlMapper">
   <Scope>apiproxy</Scope>
   <Get assignTo="urlencoding.shorturl" index='1'>
      <Key>
         <Parameter ref="urlencoding.requesturl.hashed"/>
      </Key>
   </Get>
</KeyValueMapOperations>

<KeyValueMapOperations name="getEncrypted" mapIdentifier="encrypted_map">
   <Scope>apiproxy</Scope>
   <Get assignTo="private.encryptedVar" index='1'>
      <Key>
         <Parameter>foo</Parameter>
      </Key>
   </Get>
</KeyValueMapOperations>

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

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

<KeyValueMapOperations async="false" continueOnError="false"
    enabled="true" name="Key-Value-Map-Operations-1"
    mapIdentifier="urlMapper" >
   <DisplayName>Key Value Map Operations 1</DisplayName>
   <Scope>environment</Scope>
   <ExpiryTimeInSecs>300</ExpiryTimeInSecs>
   <InitialEntries>
      <Entry>
         <Key>
            <Parameter>key_name_literal</Parameter>
         </Key>
         <Value>value_literal</Value>
      </Entry>
      <Entry>
         <Key>
            <Parameter>variable_name</Parameter>
         </Key>
         <Value>value_1_literal</Value>
         <Value>value_2_literal</Value>
      </Entry>
   </InitialEntries>
   <Put override="false">
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value ref="variable_name"/>
   </Put>
   <Get assignTo="myvar" index="1">
      <Key>
         <Parameter ref="variable_name"/>
      </Key>
   </Get>
   <Delete>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
   </Delete>
</KeyValueMapOperations>

Атрибуты <KeyValueMapOperations>

В примере ниже показаны атрибуты тега <KeyValueMapOperations>:

<KeyValueMapOperations async="false" continueOnError="false" enabled="true" name="Key-Value-Map-Operations-1" mapIdentifier="map_name">

В таблице ниже описаны атрибуты, относящиеся к тегу <KeyValueMapOperations>.

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

Элемент <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Элемент <Delete>

Удаляет указанную пару "ключ-значение". Необходимо использовать хотя бы одно из свойств <Get>, <Put> или <Delete>.

Обязательно укажите название KVM с помощью атрибута mapIdentifier в родительском элементе. Пример:

<Delete>
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Delete>

Элемент <Entry>

Начальные значения для карт "ключ-значение", которые заполняются в карте "ключ-значение" при ее инициализации.

В Edge для облака размер ключа ограничен 2 КБ. Пример:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

Элемент <ExclusiveCache>

Устаревший метод. Вместо него используйте элемент <Scope>.

Элемент <ExpiryTimeInSecs>

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

Если указать значение 0 или -1 либо не включать этот элемент, будет использоваться значение по умолчанию – 300 секунд. Пример:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

Хранилище пар "ключ-значение" – это механизм долгосрочного хранения, который сохраняет ключи и значения в базе данных NoSQL. Поэтому чтение из KVM во время выполнения может замедлить работу прокси. Чтобы повысить производительность, Edge имеет встроенный механизм кеширования ключей и значений KVM в памяти во время выполнения. Это правило операций KVM всегда считывает данные из кеша для операций GET.

Элемент <ExpiryTimeInSecs> позволяет указать, как долго ключи и значения, используемые в правиле, хранятся в кеше, прежде чем они будут обновлены из KVM. Однако есть некоторые различия в том, как операции GET и PUT влияют на срок действия кеша.

GET – при первом выполнении операции GET KVM запрошенные ключи/значения из KVM (название которого указано в корневом атрибуте mapIdentifier политики) загружаются в кеш, где остаются для последующих операций GET, пока не произойдет одно из следующих событий:

• Прошло количество секунд, указанное в <ExpiryTimeInSecs>.
  или
• Операция PUT в правиле KVM перезаписывает существующие значения (об этом рассказывается ниже).

PUT – операция PUT записывает ключи и значения в указанное хранилище пар "ключ-значение". Если команда PUT записывает данные в ключ, который уже есть в кеше, кеш немедленно обновляется и теперь содержит новое значение в течение количества секунд, указанного в элементе <ExpiryTimeInSecs> правила.

Пример: кеширование KVM

1. Операция GET извлекает значение "rating", которое добавляет в кеш значение "10". Значение параметра <ExpiryTimeInSecs> в правилах – 60.
2. Через 30 секунд политика GET выполняется снова и извлекает из кеша значение "10".
3. Через пять секунд правило PUT обновляет значение "рейтинг" до "8", а <ExpiryTimeInSecs> в правиле PUT равно 20. Кеш немедленно обновляется, и новое значение будет храниться в нем 20 секунд. (Если бы запроса PUT не было, кеш, изначально заполненный первым запросом GET, существовал бы ещё 30 секунд, оставшиеся от исходных 60 секунд.)
4. Через 15 секунд выполняется ещё один запрос GET, который получает значение "8".

Элемент <Get>

Извлекает значение для указанного ключа. Необходимо использовать хотя бы одно из свойств <Get>, <Put> или <Delete>.

Обязательно укажите название хранилища пар "ключ-значение" с помощью атрибута mapIdentifier в родительском элементе.

В правила можно включить несколько блоков Get, чтобы получить несколько элементов из хранилища пар "ключ-значение".

Как получить один объект из KVM

<Get assignTo="myvar" index="1">
   <Key>
      <Parameter>key_name_literal</Parameter>
   </Key>
</Get>

Как получить несколько объектов из KVM

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

Ниже приведен пример конфигурации правила KVM, которое можно использовать для получения названия самого популярного фильма и имени его режиссера:

<Get assignTo="top.movie.pick" index="1">
   <Key>
      <Parameter>top_movies</Parameter>
   </Key>
</Get>
<Get assignTo="movie.director">
   <Key>
      <Parameter ref="top.movie.pick"/>
   </Key>
</Get>

При вызове прокси-сервера API Edge создает следующие переменные, которые можно использовать в потоке прокси-сервера API:

• top.movie.pick=Princess Bride
• movie.director=Rob Reiner

Атрибуты

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

<Get assignTo="private.myvar">

Элемент <InitialEntries>

Начальные значения для карт пар "ключ-значение", которые заполняются в карте пар "ключ-значение" при ее инициализации. Обязательно укажите название хранилища пар "ключ-значение" с помощью атрибута mapIdentifier в родительском элементе. Пример:

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>key_name_literal</Parameter>
      </Key>
      <Value>v1</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>key_name_variable</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

При использовании этого элемента при сохранении правила в интерфейсе управления в развернутой версии прокси-сервера или развертывании пакета прокси-сервера API, содержащего правило с этим элементом, ключ(и) автоматически создаются в KVM (в незашифрованном виде). Если значения в правиле отличаются от значений в KVM, при развертывании прокси-сервера значения в KVM перезаписываются. Новые ключи и значения добавляются в существующий KVM вместе с имеющимися.

Ключи и значения, заданные в этом элементе, должны быть литералами. Например, в этом элементе не поддерживается макрос <Parameter ref="request.queryparam.key">.

Размер ключа ограничен 2 КБ как для Edge в общедоступном облаке, так и для Edge в частном облаке. Значение KVM не может превышать 2 КБ.

Чтобы создать зашифрованную карту KVM, используйте API управления картами "ключ-значение".

Элемент <Key>

Указывает ключ в записи карты "ключ-значение". Ключ может быть составным, то есть для его создания можно добавить несколько параметров. Например, поля userID и role можно объединить в поле key. Пример:

<Key>
    <Parameter>key_name_literal</Parameter>
</Key>

Ознакомьтесь с информацией об элементе <Parameter>, чтобы узнать, как задать название ключа.

В Edge для общедоступного облака размер ключа ограничен 2 КБ. Подробнее о различиях между API Edge для общедоступного и частного облака…

Элемент <Parameter>

Указывает ключ в паре "ключ-значение". Этот элемент указывает название при создании, размещении, получении или удалении пары "ключ-значение".

Указать название можно с помощью:

• строка-литерал;

  <Key>
    <Parameter>literal</Parameter>
  </Key>

• Переменная, которая будет получена во время выполнения, с помощью атрибута ref.

  <Key>
    <Parameter ref="variable_name"/>
  </Key>

• Сочетание литералов и ссылок на переменные.

  <Key>
    <Parameter>targeturl</Parameter>
    <Parameter ref="apiproxy.name"/>
    <Parameter>weight</Parameter>
  </Key>

Если элемент Key содержит несколько элементов Parameter, эффективная строка ключа представляет собой конкатенацию значений каждого параметра, соединенных двойным подчеркиванием. Например, если в приведенном выше примере переменная apiproxy.name имеет значение "abc1", то эффективным ключом будет targeturl__abc1__weight.

При получении, обновлении или удалении записи "ключ-значение" название ключа должно совпадать с названием ключа в карте "ключ-значение". Ознакомьтесь с правилами указания и получения названий ключей.

Атрибуты

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

Элемент <Put>

Записывает пару "ключ-значение" в карту пар "ключ-значение", независимо от того, зашифрована она или нет. Если карта значений ключей, указанная в атрибуте mapIdentifier родительского элемента, не существует, она будет создана автоматически (без шифрования). Если карта "ключ-значение" уже существует, ключ и значение будут добавлены в нее.

Чтобы создать зашифрованную карту пар "ключ-значение", используйте API управления картами пар "ключ-значение" или следуйте инструкциям в разделе Создание и изменение карт пар "ключ-значение" на уровне среды, чтобы создать зашифрованные карты пар "ключ-значение" на уровне среды в интерфейсе.

<Put override="false">
   <Key>
      <Parameter ref="mykeyvar"/>
   </Key>
   <Value ref="myvalvar1"/>
</Put>

Атрибуты

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

Элемент <Scope>

Определяет границу доступности для карт со значениями ключей. Область действия по умолчанию – environment. Это означает, что по умолчанию записи карт используются совместно всеми прокси API, работающими в среде (например, тестовой или рабочей). Если вы зададите область действия apiproxy, записи в карте "ключ-значение" будут доступны только прокси-серверу API, который записывает значения в карту.

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

<Scope>environment</Scope>

Элемент <Value>

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

<!-- Specify a literal value -->
<Value>literal<Value>

Или:

<!-- Specify the name of variable value to be populated at run time. -->
<Value ref="variable_name"/>

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

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

• Ключ k1 со значениями v1,v2
• Ключ k2 со значениями v3,v4

<InitialEntries>
   <Entry>
      <Key>
         <Parameter>k1</Parameter>
      </Key>
      <Value>v1</Value>
      <Value>v2</Value>
   </Entry>
   <Entry>
      <Key>
         <Parameter>k2</Parameter>
      </Key>
      <Value>v3</Value>
      <Value>v4</Value>
   </Entry>
</InitialEntries>

В следующем примере создается один ключ с двумя значениями. Предположим, название организации – foo_org, название прокси-сервера API – bar, а название среды – test.

• Ключ foo_org со значениями bar,test

<Put>
    <Key>
        <Parameter ref="organization.name"/>
    </Key>
    <Value ref="apiproxy.name"/>
    <Value ref="environment.name"/>
</Put>

Атрибуты

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

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

Ошибки, возвращаемые правилами Edge, имеют единый формат, описанный в справочнике кодов ошибок.

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

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

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

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

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

Схемы

Примечания

Общую информацию о картах пар "ключ-значение" можно найти в статье Как работать с картами пар "ключ-значение".

Хранилище карт "ключ-значение" предоставляет простой механизм сохранения данных, отформатированных как пары "ключ-значение". Вы можете получить доступ к ним во время выполнения с помощью правил или кода. Карта содержит произвольные данные в формате key=value.

например localhost=127.0.0.1, zip_code=94110 или first_name=felix. В первом примере localhost – это ключ, а 127.0.0.1 – значение. Каждая пара "ключ-значение" хранится как запись в карте "ключ-значение". Карта "ключ-значение" может содержать много записей.

Ниже приведен пример использования карт пар "ключ-значение". Предположим, вам нужно сохранить список IP-адресов, связанных с различными серверными средами. Вы можете создать карту пар "ключ-значение" с названием ipAddresses, которая будет содержать список пар "ключ-значение" в качестве записей. Например, этот код JSON может представлять такую карту:

{
  "entry" : [ {
    "name" : "Development",
    "value" : "65.87.18.18"
  }, {
    "name" : "Staging",
    "value" : "65.87.18.22"
  } ],
  "name" : "ipAddresses"
}

Эту структуру можно использовать для создания хранилища IP-адресов, которые могут применяться в правилах во время выполнения для принудительного добавления в белый или черный список, динамического выбора целевого адреса внутреннего сервера и т. д. Как правило, правила KeyValueMapOperations используются для хранения или получения долгоживущей информации, которая должна быть повторно использована в нескольких транзакциях запроса/ответа.

Картами "ключ-значение" можно управлять с помощью правила KeyValueMapOperations или напрямую через API управления Apigee Edge. Подробную информацию об API Organization key/value maps API можно найти в справочнике по Management API. Например, с помощью API можно загружать большие наборы данных в хранилище пар "ключ-значение" или создавать скрипты для управления записями в карте пар "ключ-значение". Чтобы получить доступ к карте "ключ-значение" с помощью правила KeyValueMapOperations, вам нужно создать ее с помощью API.

Как задавать и получать названия ключей

С помощью элементов <Parameter> и <Value> можно указать либо литеральное значение (между открывающим и закрывающим тегами), либо атрибут ref, чтобы задать имя переменной, значение которой будет использоваться во время выполнения.

Элемент Parameter заслуживает особого внимания, поскольку он определяет название создаваемого ключа, а также название ключа, который вы хотите получить или удалить. Ниже приведены два примера. Первый вариант задает название ключа в явном виде, а второй – с помощью переменной. Предположим, что для создания ключей в KVM используются следующие значения:

<Parameter>key_name_literal</Parameter>
<Parameter ref="key.name.variable"/>

В первом случае в хранилище пар "ключ-значение" в качестве названия ключа сохраняется буквальное значение "key_name_literal". Во втором случае значение key.name.variable становится названием ключа в хранилище пар "ключ-значение". Например, если в key.name.variable содержится значение foo, ключ будет называться "foo".

Если вы хотите получить ключ и его значение с помощью операции GET (или удалить с помощью операции DELETE), параметр <Parameter> должен соответствовать названию ключа в KVM. Например, если имя ключа в хранилище пар "ключ-значение" – foo, вы можете указать либо литеральное значение с помощью <Parameter>foo</Parameter>, либо переменную, которая содержит точное значение foo, например <Parameter ref="variable.containing.foo"/>.

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

• API для карт "ключ-значение" организации