Поделиться через

Политики в службе "Управление API Azure"

ПРИМЕНЯЕТСЯ КО ВСЕМ уровням управления API

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

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

К популярным политикам относятся:

  • Преобразование формата из XML в JSON.
  • Ограничение частоты звонков, ограничивающее количество входящих звонков от разработчика.
  • Фильтрация запросов, поступающих из определенных IP-адресов.

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

Общая информация о конфигурации политики

Определения политик — это простые XML-документы, описывающие последовательность инструкций для применения к запросам и ответам. Чтобы помочь вам настроить определения политик, портал предоставляет следующие параметры:

  • Интерактивный редактор на основе форм для упрощения настройки популярных политик без написания кода XML
  • Редактор кода, в котором можно вставлять фрагменты XML или редактировать XML напрямую.

Дополнительные сведения о настройке политик см. в разделе "Настройка" или "Изменение политик".

Конфигурация XML политики делится на разделы inbound, backend, outbound и on-error. Эта серия указанных политических заявлений выполняется в порядке для обработки запросов и ответов. Вот как выглядит:

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there's an error condition go here -->
  </on-error>
</policies>

Примеры XML политики см. в репозитории политик управления API.

Обработка ошибок

Если во время обработки запроса возникает ошибка:

  • Любые оставшиеся шаги в inbound, backend, или outbound разделах пропускаются.
  • Выполнение переходит к инструкциям в on-error разделе.

Поместив инструкции политики в on-error раздел, вы можете:

  • Просмотрите ошибку, используя свойство context.LastError.
  • Проверьте и настройте ответ на ошибку, используя политику set-body.
  • Настройте то, что происходит при возникновении ошибки.

Дополнительные сведения см. в статье об обработке ошибок в политиках управления API.

Выражения политики

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

  • Одна инструкция C#, заключенная в @(expression)
  • Блок кода C# с несколькими операторами, заключенный в @{expression}, который возвращает значение.

У каждого выражения есть доступ к неявно заданной переменной context и разрешенному подмножеству типов платформы .NET Framework.

Выражения политики предоставляют сложные средства для управления трафиком и изменения поведения API, не требуя написания специализированного кода или изменения внутренних служб. Некоторые политики основаны на выражениях политики, таких как поток управления и переменная Set.

Области применения

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

  • Глобальные (все API)
  • Рабочая область (все API, связанные с выбранной рабочей областью)
  • Продукт (все API, связанные с выбранным продуктом)
  • API (все операции в API)
  • Операция (одна операция в API)

При настройке политики необходимо сначала выбрать область, в которой применяется политика.

Схема, демонстрирующая пять областей политики.

Вещи, которые нужно знать

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

  • Не все политики поддерживаются в каждой области и каждом разделе политики.

  • При настройке определений политик в нескольких областях вы управляете наследованием политик и порядком оценки политики в каждом разделе политики путем размещения base элемента.

    Это важно

    Рекомендуется включить base элемент в начале каждого раздела политики, чтобы наследовать политики от родительской области. Это гарантирует, что любые политики, определенные на более высоком уровне, непреднамеренно переопределяются или игнорируются. Встроенное определение политики Azure (API Management policies should inherit parent scope policies using <base/>) доступно для аудита или применения этой рекомендации.

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

    Замечание

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

Дополнительные сведения можно найти здесь

Политики резолвера GraphQL

В системе управления API сопоставитель GraphQL настраивается политиками, охватывающими определенный тип операции и поле в схеме GraphQL.

  • В настоящее время управление API поддерживает сопоставители GraphQL, которые указывают либо HTTP API, Azure Cosmos DB, либо источники данных SQL Azure. Например, можно настроить одну http-data-source политику с элементами, чтобы указать запрос (и необязательно ответ от) источника данных HTTP.
  • Политику сопоставителя нельзя включить в определения политик в других областях, таких как API, продукт или все API. Политика также не наследует политики, сконфигурированные в других областях.
  • Шлюз оценивает политику в рамках решателя после любой настройки политик inbound и backend в цепочке выполнения политики.

Дополнительные сведения см. в разделе "Настройка сопоставителя GraphQL".

Воспользуйтесь помощью Copilot

Вы можете получить помощь по искусственному интеллекту от Copilot для создания и изменения определений политик управления API. Вы можете использовать Copilot для создания и обновления политик, соответствующих определенным требованиям, без необходимости знать синтаксис XML. Вы также можете получить объяснения существующих политик. И Copilot может помочь вам перевести политики, которые, возможно, были настроены в других решениях по управлению API.

  • Microsoft Copilot в Azure предоставляет помощь по разработке политик с запросами на естественном языке на портале Azure. Вы можете создать политики в редакторе политик управления API и попросить Copilot объяснить разделы политики.
  • GitHub Copilot для Azure в Visual Studio Code предоставляет помощь по разработке политик в Visual Studio Code, и вы можете использовать расширение управления API Azure для Visual Studio Code для ускорения настройки политики. Вы можете использовать естественный язык, чтобы запросить у Copilot Chat или Copilot Edits создание и уточнение определений политики на месте.

Пример запроса:

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot работает на основе искусственного интеллекта, поэтому возможны сюрпризы и ошибки. Подробности см. в Общие вопросы об использовании Copilot.

Примеры

Применение политик, заданных в разных областях

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

Пример определения политики в области API:

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

В приведенном выше примере определения политики:

  • Инструкция cross-domain выполняется сначала.
  • Политика find-and-replace выполняется после любых политик на более общем уровне.

Замечание

Если удалить base элемент в области API, будут применены только политики, настроенные в области API. Политики, настроенные на уровне продукта и более широких масштабов, не будут применяться.

Использование выражений политики для изменения запросов

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

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Связанный контент

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

  • Last updated on