Share via

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

  • Статья

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

В службе Azure API Management издатели API могут изменять поведение API посредством настройки с помощью политик. Политика — это коллекция правил, которые выполняются последовательно над запросом или ответом API. Управление API предоставляет более 50 политик из поля, которые можно настроить для решения распространенных сценариев 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 is 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 элемента

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

    Примечание.

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

Дополнительные сведения см. в разделе:

Политики сопоставителя GraphQL

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

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

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

Получение помощи в создании политик с помощью Microsoft Copilot для Azure (предварительная версия)

Microsoft Copilot для Azure (предварительная версия) предоставляет возможности разработки политик для Управление API Azure. Используйте Copilot для Azure в контексте редактора политик Управление API, чтобы создавать политики, соответствующие определенным требованиям, не зная синтаксиса или уже настроенные политики.

Вы можете предложить Copilot Azure создать определения политик, а затем скопировать результаты в редактор политик и внести необходимые корректировки. Задайте вопросы для получения аналитических сведений о различных вариантах, изменения предоставленной политики или уточнения уже существующей политики. Подробнее

Внимание

Microsoft Copilot для Azure (предварительная версия) требует регистрации и в настоящее время доступен только утвержденным корпоративным клиентам и партнерам. Дополнительные сведения см. в статье "Ограниченный доступ к Microsoft Copilot для Azure (предварительная версия)".

Примеры

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

Если у вас есть политика на глобальном уровне и политика, настроенная для 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>

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

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