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

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

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

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

Сценарии KVM

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

  • У вас есть API-прокси, которому необходимо вызывать один целевой URL (или URL-адрес вызова сервиса) в тестовой среде и другой целевой URL в производственной среде. Вместо того чтобы жестко прописывать URL-адреса в вашем прокси, вы можете настроить прокси так, чтобы он определял, в какой среде он находится, выполнял соответствующую политику сопоставления ключей и значений и получал правильный целевой URL-адрес из одной из созданных вами KVM. А позже, если один или оба ваших целевых URL-адреса изменятся, вы просто обновите 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 в среде «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"
}

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

При использовании политики «Операции сопоставления ключей и значений» для получения зашифрованных значений 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-переключатели можно следующими способами:

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

    Для создания и обновления KVM во время выполнения с помощью ваших API-прокси используйте политику «Операции сопоставления ключей и значений» . (В политике вы указываете имя KVM в атрибуте mapIdentifier родительского элемента.)

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

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

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

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

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

    Для создания зашифрованного 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 > Конфигурация среды > Сопоставление ключей и значений (классический Edge) или Администрирование > Среды > Сопоставление ключей и значений (новый Edge).

Пример KVM

Пример использования KVM для заполнения значений в URL-адресе см. в разделе «Создание шаблона целевого URL-адреса с помощью KVM в зависимости от среды» .