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

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

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

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

KVM-сценарии

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

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

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

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

У KVM есть возможности

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

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

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

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

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

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

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

Пограничный интерфейс

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

API управления

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

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

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

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

Пределы

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

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

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

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

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

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

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

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

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

    Для создания и обновления 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 во время выполнения используйте политику операций с картой значений ключей в своих прокси).

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

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

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

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

Получение KVM

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

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

Пример KVM

Пример использования KVM для заполнения значений в URL-адресе см. в https://community.apigee.com/questions/32727/templatize-target-url-with-kvm-by-environment.html .