Знакомство с политиками службы "Управление API"

  • 3 мин

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

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

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

Определение политики представляет собой простой 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>

Если во время обработки запроса возникает ошибка, все оставшиеся шаги в inboundразделах , backendили outbound пропускаются, а выполнение переходит к операторам on-error в разделе. Поместив операторы политики в раздел on-error, вы можете просмотреть ошибку с помощью свойства context.LastError, изучить и настроить ответ на ошибку с помощью политики set-body, а также настроить, что именно происходит при возникновении ошибки.

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

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

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

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

Выражения политики предоставляют сложные средства для управления трафиком и изменения поведения 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>

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

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

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

В предыдущем примере определения cross-domain политики оператор будет выполняться первым. Политика find-and-replace будет выполняться после всех политик, действующих в более широкой области.

Фильтрация содержимого ответа

Политика, определенная в следующем примере, демонстрирует фильтрацию элементов данных из полезных данных ответа на основе продукта, связанного с запросом.

Во фрагменте предполагается, что содержимое ответа имеет формат JSON и содержит свойства корневого уровня с именами minutely, hourly, daily, flags.

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <choose>
      <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
        <!-- NOTE that we are not using preserveContent=true when deserializing response body stream into a JSON object since we don't intend to access it again. See details on https://learn.microsoft.com/azure/api-management/api-management-transformation-policies#SetBody -->
        <set-body>
          @{
            var response = context.Response.Body.As<JObject>();
            foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
            response.Property (key).Remove ();
           }
          return response.ToString();
          }
    </set-body>
      </when>
    </choose>    
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>