Политика KeyValueMapOperations

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

Что

Предоставляет доступ на основе политик к хранилищу Key Value Map (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>

<Удалить> элемент

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

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

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

<Входной> элемент

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

Для 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 обновляет кэшированное значение из указанного KVM.

Значение 0 или -1, или отсутствие этого элемента, означает использование значения по умолчанию — 300 секунд. Например:

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

KVM — это механизм долговременного хранения данных, который сохраняет ключи и значения в базе данных NoSQL. Из-за этого чтение из KVM во время выполнения может потенциально замедлить работу прокси-сервера. Для повышения производительности Edge имеет встроенный механизм кэширования ключей/значений KVM в памяти во время выполнения. Эта политика операций KVM всегда считывает данные из кэша для операций GET.

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

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

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

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

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

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

<Получить> элемент

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

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

В политику можно включить несколько блоков Get для получения нескольких элементов из KVM.

Получить один элемент с 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>

Начальные значения для карт ключ-значение, которые заполняются в карте ключ-значение при ее инициализации. Обязательно укажите имя KVM с помощью атрибута 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 для публичного облака и API частного облака» .

Элемент <Параметр>

Указывает ключ в паре ключ/значение. Этот элемент задаёт имя при создании, добавлении, извлечении или удалении пары ключ/значение.

Вы можете указать имя, используя:

• Буквальная строка

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

<Поместить> элемент

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

Для создания зашифрованной карты ключ-значение используйте API управления картами ключ-значение ; или см. раздел «Создание и редактирование карт ключ-значение среды» для создания зашифрованных KVM-объектов с областью действия в среде в пользовательском интерфейсе.

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

Атрибуты

В следующей таблице описаны атрибуты элемента <Put> :

<Область> элемент

Определяет границы доступности для карт ключ-значение. Область видимости по умолчанию — 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-адресов, которое может применяться политиками во время выполнения для принудительного включения IP-адресов в список разрешенных или запрещенных, для динамического выбора целевого адреса бэкэнда и так далее. Как правило, политика KeyValueMapOperations используется для хранения или извлечения долговременной информации, которую необходимо повторно использовать в нескольких транзакциях запроса/ответа.

Карты «ключ/значение» можно изменять с помощью политики KeyValueMapOperations или напрямую через API управления Apigee Edge. Подробную информацию об API карт «ключ/значение» для организации см. в справочнике API управления. Вы можете использовать API, например, для загрузки больших наборов данных в хранилище «ключ/значение» или для создания скриптов для управления записями карт «ключ/значение». Перед доступом к карте «ключ/значение» с помощью политики KeyValueMapOperations необходимо создать карту «ключ/значение» с помощью API.

Указание и получение имен ключей

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

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

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

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

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

Связанные темы

• API для сопоставления ключей и значений в организации