Работа с картами ключ-значение

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

Иногда требуется хранить данные для извлечения во время выполнения — данные с неограниченным сроком действия, которые не следует жестко прописывать в логике прокси-API. Карты ключей и значений (KVM) идеально подходят для этого. KVM — это настраиваемая коллекция пар «ключ/значение», которая может быть зашифрована или не зашифрована. Вот два примера:

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

сценарии KVM

Вот несколько ситуаций, когда KVM могут пригодиться:

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

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

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

У KVM есть область применения

Область действия означает «где доступен KVM». KVM могут быть созданы в следующих областях действия: organization , environment и apiproxy .

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

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

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

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

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

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

Edge UI

Зашифрованные карты значений ключей отображают значения, замаскированные звёздочками в пользовательском интерфейсе (*****). Например:

API управления

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

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

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

При использовании политики Key Value Map Operations для получения зашифрованных значений KVM вы указываете имя переменной для хранения этого значения. Чтобы получить зашифрованное значение, необходимо добавить префикс « private. » к имени переменной, что предотвращает отображение ключей/значений KVM в сеансах трассировки и отладки.

Пределы

В организациях с включенными службами Core Persistence Services (CPS) :

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

Для Apigee Edge for Private Cloud размер каждого KVM не должен превышать 15 МБ (это суммарный размер ключей и значений). При превышении этого ограничения Apigee Edge for Private Cloud вернёт ошибку. Чтобы определить размер ваших KVM, воспользуйтесь командой nodetool cfstats .

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

Управление и использование KVM

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

Создание и обновление KVM

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

  • Политика операций Key Value Map (без шифрования)

    Для создания и обновления KVM во время выполнения с помощью прокси-серверов API используйте политику Key Value Map Operations . (В этой политике имя KVM указывается в атрибуте mapIdentifier родительского элемента.)

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

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

  • API управления

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

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

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

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

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

Извлечение KVM

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

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

Пример KVM

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