Бөлісу құралы:

Использование именованных значений в политиках Управления API Azure

  • Мақала

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

Политики Управления API представляют собой одну из эффективных функций системы, позволяющих издателю изменять поведение интерфейса API путем его настройки. Политика — это коллекция правил, которые выполняются последовательно над запросом или ответом API. Для создания правил политики можно использовать литеральные текстовые значения, выражения политики и именованные значения.

Именованные значения являются глобальной коллекцией пар "имя/значение" в каждом экземпляре Управления API. В коллекции не налагаются ограничения по числу элементов. Именованные значения можно использовать для управления постоянными строковыми значениями во всей конфигурации и политиках API.

Именованные значения на портале Azure

Типы значений

Тип Описание
Обычный Литеральная строка или выражение политики
Секретный Литеральная строка или выражение политики, зашифрованные службой Управления API
Key vault Идентификатор секрета, хранящегося в хранилище ключей Azure.

Обычные значения или секреты могут содержать выражения политики. Например, выражение @(DateTime.Now.ToString()) возвращает строку, содержащую текущую дату и время.

Дополнительные сведения об атрибутах именованного значения см. в справочнике REST API по Управлению API.

Секреты хранилища ключей

Значения секрета могут храниться либо в зашифрованных строках в Управлении API (пользовательские секреты), либо в виде ссылок на секреты в Azure Key Vault.

Рекомендуется использовать секреты хранилища ключей, так как это улучшает безопасность Управления API:

  • Секреты, хранящиеся в хранилищах ключей, можно повторно использовать в разных службах
  • К секретам можно применять политики детализированного доступа
  • Секреты, обновленные в хранилище ключей, автоматически меняются в управлении API. После обновления в хранилище ключей именованное значение в Управлении API обновляется в течение 4 часов. Можно также вручную обновить секрет на портале Azure или с помощью REST API управления.

Примечание.

Секреты, хранящиеся в Azure Key Vault, должны находиться в диапазоне от 1 до 4096 символов, так как Управление API не могут получить значения, превышающие это ограничение.

Необходимые компоненты

Предварительные требования для интеграции с хранилищем ключей

Примечание.

В настоящее время эта функция недоступна в рабочих областях.

Настройка доступа к хранилищу ключей

  1. На портале перейдите к хранилищу ключей.

  2. В меню слева выберите конфигурацию Access и запишите настроенную модель разрешений.

  3. В зависимости от модели разрешений настройте политику доступа к хранилищу ключей или доступ Azure RBAC для управляемого удостоверения Управление API.

    Чтобы добавить политику доступа к хранилищу ключей, выполните следующие действия.

    1. В меню слева выберите политики доступа.
    2. На странице политик доступа нажмите кнопку +Создать.
    3. На вкладке "Разрешения" в разделе "Разрешения секрета" выберите "Получить" и "Список", а затем нажмите кнопку "Далее".
    4. На вкладке "Субъект" выберите субъект, найдите имя ресурса управляемого удостоверения и нажмите кнопку "Далее". Если вы используете назначаемое системой удостоверение, субъектом является имя экземпляра Управления API.
    5. Снова выберите Далее. На вкладке Проверить и создать выберите Создать.

    Чтобы настроить доступ к Azure RBAC, выполните приведенные действия.

    1. В меню слева выберите Управление доступом (IAM).
    2. На странице управления доступом (IAM) выберите " Добавить назначение роли".
    3. На вкладке "Роль" выберите "Пользователь сертификата Key Vault".
    4. На вкладке "Члены" выберите "Управляемое удостоверение>" и "Выбрать участников".
    5. На странице "Выбор управляемого удостоверения" выберите управляемое удостоверение, назначаемое системой, или назначаемое пользователем управляемое удостоверение, связанное с экземпляром Управление API, а затем нажмите кнопку "Выбрать".
    6. Выберите Проверить + назначить.

Требования к брандмауэру хранилища ключей

Если хранилище ключей поддерживает брандмауэр, см. дополнительные требования ниже.

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

  • В брандмауэре хранилища ключей установите флажок Разрешить доверенным службам Майкрософт обходить этот брандмауэр.

  • Убедитесь, что IP-адрес локального клиента временно может получить доступ к хранилищу ключей при выборе сертификата или секрета для добавления в Azure API Management. Дополнительные сведения см. в разделе Настройка сетевых параметров Azure Key Vault.

    После завершения настройки можно заблокировать адрес клиента в брандмауэре хранилища ключей.

Требования к виртуальной сети

Если экземпляр службы управления API развернут в виртуальной сети, настройте также следующие параметры сети.

  • Включите конечную точку службы для Azure Key Vault в подсети службы управления API.
  • Настройте правило группы безопасности сети (NSG), разрешающее исходящий трафик для тегов службы AzureKeyVault и AzureActiveDirectory.

Дополнительные сведения приведены в статье Конфигурация сети при настройке Управления API Azure в виртуальной сети.

Добавление или изменение именованного значения

Добавление секрета хранилища ключей в Управление API

См. Предварительные требования для интеграции хранилища ключей.

Внимание

При добавлении секрета хранилища ключей в экземпляр Управление API необходимо иметь разрешения на получение списка секретов из хранилища ключей.

Внимание

При использовании секрета хранилища ключей в Управлении API следует избегать удаления секрета, хранилища ключей или управляемого удостоверения, используемого для доступа к хранилищу ключей.

  1. Перейдите к экземпляру Управления API на портале Azure.

  2. В разделе API выберите Именованные значения > + Добавить.

  3. Введите идентификатор Имя и введите Отображаемое имя, используемое для ссылки на свойство в политиках.

  4. В списке Тип значения выберите Хранилище ключей.

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

    Внимание

    Если вы вводите идентификатор секрета в хранилище ключей самостоятельно, убедитесь, что у него отсутствуют сведения о версии. В противном случае секрет не будет автоматически меняться в Управлении API после обновления в хранилище ключей.

  6. В списке Удостоверение клиента выберите назначаемое системой или существующее управляемое удостоверение, назначаемое пользователем. Узнайте, как добавлять или изменять управляемые удостоверения в своей службе Управления API.

    Примечание.

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

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

  8. Нажмите кнопку создания.

    Добавление значения секрета хранилища ключей

Добавление обычного или секретного значения в Управление API

  1. Перейдите к экземпляру Управления API на портале Azure.
  2. В разделе API выберите Именованные значения > + Добавить.
  3. Введите идентификатор Имя и введите Отображаемое имя, используемое для ссылки на свойство в политиках.
  4. В списке Тип значения выберите Обычный или Секрет.
  5. В списке Значение введите строку или выражение политики.
  6. Добавьте один или несколько необязательных тегов, чтобы помочь упорядочить именованные значения, а затем нажмите кнопку Сохранить.
  7. Нажмите кнопку создания.

После создания именованного значения вы можете изменить его по имени. Если вы измените отображаемое имя, все политики, ссылающиеся на это именованное значение, автоматически обновятся для использования нового имени.

Использование именованного значения

В примерах в этом разделе используются именованные значения, приведенные в следующей таблице.

Имя. Значение Секретный
ContosoHeader TrackingId False
ContosoHeaderValue •••••••••••••••••••••• Истина
ExpressionProperty @(DateTime.Now.ToString()) False
ContosoHeaderValue2 This is a header value. False

Чтобы использовать именованное значение в политике, поместите его отображаемое имя в двойные пары фигурных скобок, например {{ContosoHeader}}, как показано в следующем примере.

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

В этом примере ContosoHeader используется как имя заголовка в политике set-header, а ContosoHeaderValue — в качестве значения этого заголовка. При оценке этой политики во время запроса или ответа к шлюзу Управления API {{ContosoHeader}} и {{ContosoHeaderValue}} заменяются соответствующими значениями.

Именованные значения можно использовать в качестве полных значений атрибута или элемента, как показано в предыдущем примере, но их также можно вставить в или объединить с частью текстового выражения литерального текста, как показано в следующем примере:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Кроме того, именованные значения могут содержать выражения политики. В следующем примере используется выражение ExpressionProperty.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

При оценке этой политики {{ExpressionProperty}} заменяется своим значением @(DateTime.Now.ToString()). Поскольку значение является выражением политики, выражение проходит оценку и политика продолжает выполнение.

Это можно проверить на портале Azure или на портале разработчика, вызвав операцию, в область действия которой входят именованные свойства. В следующем примере вызывается операция с двумя политиками set-header с именованными значениями из предыдущего примера. Обратите внимание, что ответ содержит два пользовательских заголовка, которые были настроены с помощью политик с именованными значениями.

Проверка ответа API

В трассировке API для вызова, который содержит две политики с именованными значениями из предыдущего примера, вы увидите две политики set-header со вставленными именованными значениями, а также оценку выражения политики для именованного значения, которое содержало это выражение политики.

Трассировка с помощью инспектора API

Интерполяция строк также может использоваться с именованными значениями.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

Значением CustomHeader будет The URL encoded value is This+is+a+header+value..

Внимание

Если политика ссылается на секрет в Azure Key Vault, значение из хранилища ключей будет отображаться для пользователей, имеющих доступ к подпискам, для которых включена Трассировка запросов API.

Хотя именованные значения могут содержать выражения политики, они не могут содержать другие именованные значения. Если в качестве значения используется текст, содержащий ссылку на именованное значение (например, Text: {{MyProperty}}), эта ссылка не будет разрешена и заменена.

Удаление именованного значения

Чтобы удалить именованное значение, выберите его и в контекстном меню (...) выберите Удалить.

Внимание

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

Следующие шаги