Как работать с картами пар "ключ-значение"

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

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

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

Сценарии использования KVM

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

  • У вас есть прокси-сервер API, который должен вызывать один целевой URL (или URL вызова сервиса) в тестовой среде и другой целевой URL в рабочей среде. Вместо того чтобы жестко задавать URL в прокси, можно настроить прокси на определение среды, в которой он находится, выполнение связанного правила Key Value Map Operations и получение правильного целевого URL из одной из созданных вами карт "ключ-значение". Если впоследствии один или оба целевых URL изменятся, вам нужно будет просто обновить значения KVM. Прокси-сервер получит новые значения, и повторное развертывание прокси-сервера не потребуется.
  • Вы хотите хранить учетные данные, закрытые ключи или токены, например токены для внешних сервисов, учетные данные, необходимые для создания токенов OAuth, или закрытые ключи, используемые в вызовах Java или JavaScript для шифрования или подписи JSON Web Token (JWT). Вместо того чтобы передавать учетные данные, ключи или токены в запросе или жестко кодировать их в логике прокси, вы можете хранить их в зашифрованном виде в хранилище пар "ключ-значение" и динамически извлекать их при вызовах целевых сервисов, которым они требуются.

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

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

Область действия KVM

Область действия – это место, где доступен KVM-переключатель. Создавать пары "ключ-значение" можно на следующих уровнях: organization, environment и apiproxy.

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

Или вы можете захотеть, чтобы все прокси API в вашей тестовой среде имели доступ к карте значений ключей. В этом случае вам нужно будет создать карту значений ключей в области действия среды. Прокси-серверы, развернутые в среде prod, не могут получить доступ к KVM в области действия среды test. Если вы хотите, чтобы те же ключи KVM были доступны в рабочей среде, создайте параллельную KVM с областью действия "prod".

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

О зашифрованных KVM

Зашифрованные KVM шифруются с помощью 128-битного ключа шифрования AES, сгенерированного Apigee. Ключ, используемый для шифрования KVM, хранится в области действия KVM. Например, в организации все зашифрованные пары "ключ-значение", созданные на уровне среды, создаются с использованием одного и того же ключа на уровне среды.

В браузере Edge зашифрованные значения отображаются следующим образом: (Информацию о создании зашифрованных KVM можно найти в разделе Управление KVM и их использование.)

Интерфейс Edge

В зашифрованных картах "ключ-значение" значения в интерфейсе маскируются звездочками (*****). Пример:

Management API

В API управления зашифрованные значения возвращаются в маскированном виде. Ниже приведен пример ответа API управления на вызов Get encrypted KVM:

{
  "encrypted": true,
  "entry": [
    {
      "name": "Key1",
      "value": "*****"
    },
    {
      "name": "Key2",
      "value": "*****"
    }
  ],
  "name": "secretMap"
}

Трассировка и отладка

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

Ограничения

В организациях, где включены основные сервисы сохранения данных (CPS):

  • В названии/идентификаторе KVM учитывается регистр.
  • Размер ключа не должен превышать 2 КБ.
  • Размер значения не должен превышать 10 КБ.

В Apigee Edge для частного облака размер каждой пары "ключ-значение" не должен превышать 15 МБ (это общий размер ключей и значений). Если вы превысите это число, Apigee Edge для частного облака вернет ошибку. Чтобы определить размер хранилищ пар "ключ-значение", можно использовать команду nodetool cfstats.

Большие значения KVM могут привести к снижению производительности. Поэтому для повышения производительности рекомендуется разбивать большие монолитные KVM на более мелкие.

Как управлять переменными KVM и использовать их

Создавать, настраивать и использовать пары "ключ-значение" можно разными способами. В этом разделе описаны различные способы создания и получения зашифрованных и незашифрованных KVM.

Как создавать и обновлять пары "ключ-значение"

Создавать и обновлять пары "ключ-значение" можно следующими способами:

  • Правила в отношении операций с картой ключей-значений (без шифрования)

    Чтобы создавать и обновлять KVM во время выполнения с помощью прокси API, используйте правило операций с картой значений ключей. (В правиле вы указываете название KVM в атрибуте mapIdentifier родительского элемента.)

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

    Элемент <Put> создает новую карту KVM, если она ещё не существует, и создает ключ с одним или несколькими значениями. Если хранилище пар "ключ-значение" уже существует, пары "ключ-значение" добавляются (или обновляются, если ключ уже существует). В правиле KVM можно использовать несколько элементов <Put>.

  • Management API

    API управления предназначен для работы с хранилищами пар "ключ-значение" в качестве администратора, а не во время выполнения в прокси API. Например, у вас может быть внутренний скрипт, который использует API управления для удаления и повторного создания пар "ключ-значение" в тестовой среде, или вы можете захотеть сбросить значение ключа в паре "ключ-значение", чтобы все прокси-серверы могли его получить. (Для манипуляций с картами "ключ-значение" во время выполнения используйте правило операций с картами "ключ-значение" в прокси.)

    API управления картами "ключ-значение" позволяет создавать, обновлять и удалять зашифрованные карты "ключ-значение" и пары "ключ-значение" на всех уровнях (организация, среда и apiproxy).

    Чтобы создать зашифрованное хранилище пар "ключ-значение" с помощью API управления, добавьте "encrypted" : "true" в полезную нагрузку JSON. Шифровать пары "ключ-значение" можно только при их создании. Зашифровать существующую переменную KVM нельзя.

  • Интерфейс управления

    В интерфейсе управления Edge можно создавать и изменять KVM, действующие в пределах среды. Это единственный тип KVM, который отображается в интерфейсе. Управляемый интерфейс – это удобный способ вручную администрировать данные KVM для прокси API во время выполнения. Подробнее о том, как создавать и изменять карты пар "ключ-значение" для среды…

Получение пар "ключ-значение"

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

  • Правило. Используйте элемент <Get> в правиле операций с картой пар "ключ-значение", чтобы получить зашифрованные и незашифрованные карты пар "ключ-значение". Единственное отличие заключается в том, что при получении зашифрованных значений с помощью правила к названию переменной, которая будет содержать полученное значение, необходимо добавить префикс "private.", как описано в разделе об операции Get справочной статьи. Этот префикс скрывает значение от сеансов трассировки и отладки при отладке прокси API.
  • Management API. Для административного управления можно использовать создание и редактирование карт значений ключей среды, чтобы получать KVM и ключи/значения. Например, если вы хотите создать резервную копию карт значений ключей, получив и сохранив их определения в формате JSON, используйте Management API. Однако помните, что зашифрованные значения в ответе API отображаются как *****.
  • Интерфейс управления. Чтобы посмотреть KVM, относящиеся к определенной области действия, в интерфейсе управления, выберите API > Конфигурация среды > Карты "ключ-значение" (Classic Edge) или Администратор > Среды > Карты "ключ-значение" (New Edge).

Пример KVM

Пример использования KVM для заполнения значений в URL приведен в разделе Шаблонизация целевого URL с помощью KVM по среде.