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

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

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

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

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

Тип	Описание
Обычный	Литеральная строка или выражение политики
Секретный	Литеральная строка или выражение политики, зашифрованные службой Управления 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 не могут получить значения, превышающие это ограничение.

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

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

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

Примечание.

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

• Если у вас еще нет хранилища ключей, создайте его. Инструкции по созданию хранилища ключей см. в разделе Краткое руководство. Создание хранилища ключей с помощью портала Azure.

  Сведения о создании или импорте секрета в хранилище ключей см. в кратком руководстве по настройке и извлечению секрета из Azure Key Vault с помощью портал Azure.

• Включите назначаемое системой или назначаемое пользователем управляемое удостоверение в экземпляре Управления 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. Нажмите кнопку создания.

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

Azure CLI

Чтобы начать работу с Azure CLI:

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.

  

• Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.

  • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Чтобы добавить именованное значение, используйте команду az apim nv create:

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

После создания именованного значения его можно обновить с помощью команды az apim nv update. Для просмотра всех своих именованных значений выполните команду az apim nv list:

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

Чтобы просмотреть сведения об именованном значении, созданном для этого примера, выполните команду az apim nv show:

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Этот пример является значением секрета. Предыдущая команда не возвращает значение. Чтобы просмотреть это значение, выполните команду az apim nv show-secret:

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Чтобы удалить именованное значение, используйте команду az apim nv delete:

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

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

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

Имя.	Значение	Секретный
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 для вызова, который содержит две политики с именованными значениями из предыдущего примера, вы увидите две политики set-header со вставленными именованными значениями, а также оценку выражения политики для именованного значения, которое содержало это выражение политики.

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

<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, значение можно удалить только после удаления ссылок на него из всех этих политик.

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

• Дополнительные сведения о работе с политиками
  • Политики в управлении API
  • Справочник по политикам
  • Выражения политики