Политика 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>

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

Удаляет указанную пару ключ/значение. Должен использоваться хотя бы один из <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 обновляет свое кэшированное значение из указанного KVM.

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

<ExpiryTimeInSecs>600</ExpiryTimeInSecs>

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

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

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

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

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

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

1. Операция GET извлекает значение «рейтинг», которое добавляет в кэш значение «10». <ExpiryTimeInSecs> в политике равно 60.
2. Через 30 секунд политика GET выполняется снова и извлекает «10» из кэша.
3. Через 5 секунд политика PUT обновляет значение «рейтинг» до «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 управления картами ключей и значений .

Элемент <Ключ>

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

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

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

В Edge для публичного облака размер ключа ограничен 2 КБ. Дополнительные сведения см . в разделе «Различия между Edge для API публичного облака и 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 включает в себя несколько элементов параметра, эффективная строка ключа представляет собой объединение значений каждого параметра, объединенных двойным подчеркиванием. Например, в приведенном выше примере, если переменная apiproxy.name имеет значение «abc1», то эффективным ключом будет targeturl__abc1__weight .

Независимо от того, получаете ли вы, обновляете или удаляете запись «ключ-значение», имя ключа должно совпадать с именем ключа в карте значений ключей. Рекомендации см. в разделе Указание и получение имен ключей .

Атрибуты

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

Элемент <Put>

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

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

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

Атрибуты

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

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

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

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

<Scope>environment</Scope>

Элемент <Значение>

Указывает значение ключа. Вы можете указать значение либо как литеральную строку, либо, используя атрибут 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 управления. Вы можете использовать API, например, для загрузки больших наборов данных в хранилище ключей/значений или для создания сценариев для управления записями сопоставления ключей/значений. Вам потребуется создать карту «ключ-значение» с помощью API, прежде чем получить к ней доступ с помощью политики KeyValueMapOperations.

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

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

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

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

В первом случае буквальное значение «key_name_literal» сохраняется в KVM как имя ключа. Во втором случае любое значение в 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 карты ключей/значений организации