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

Политики в службе управления 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, подписку со всеми 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 (предварительная версия) предоставляет возможности разработки политик для Azure Управление API. Используйте Copilot в Azure в контексте редактора политик Управление API, чтобы создавать политики, соответствующие определенным требованиям, не зная синтаксиса или уже настроенные политики.

Вы можете предложить 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>

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

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