Políticas no Gerenciamento de API do Azure

  • Artigo

APLICA-SE A: todas as camadas do Gerenciamento de API

No Gerenciamento de API do Azure, os editores de API podem alterar o comportamento da API por meio da configuração usando políticas. As políticas são um conjunto de instruções executadas em sequência, na solicitação ou na resposta de uma API. O Gerenciamento de API fornece mais de 50 políticas prontas para serem configuradas para lidar com cenários comuns de API, como autenticação, limitação de taxa, cache e transformação de solicitações ou respostas. Para obter uma lista completa, consulte Referência de Política de Gerenciamento de API.

As políticas populares incluem:

  • Conversão de formato de XML para JSON
  • Limitação de fluxo de chamadas para restringir o número de chamadas recebidas de um desenvolvedor
  • Solicitações de filtragem provenientes de determinados endereços IP

As políticas são aplicadas dentro do gateway que fica entre o consumidor da API e a API gerenciada. Enquanto o gateway recebe solicitações e as encaminha, inalteradas, para a API subjacente, uma política pode aplicar alterações à solicitação de entrada e à resposta de saída.

Compreendendo configuração de políticas

As definições de política são documentos XML simples que descrevem uma sequência de instruções a serem aplicadas a solicitações e respostas. Para ajudá-lo a configurar as definições de política, o portal fornece estas opções:

  • Um editor guiado baseado em formulário para simplificar a configuração de políticas populares sem codificar XML
  • Um editor de código em que você pode inserir snippets XML ou editar XML diretamente

Para obter mais informações sobre como configurar políticas, consulte Definir ou editar políticas.

A configuração XML da política é dividida nas seções inbound, backend, outbound e on-error. Essa série de instruções de política especificadas é executada ordenadamente para uma solicitação e uma resposta.

<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>

Para obter exemplos de XML de políticas, confira Repositório de snippets da política de Gerenciamento de API.

Tratamento de erros

Se ocorrer um erro durante o processamento de uma solicitação:

  • Todas as etapas restantes nas seções inbound, backend ou outbound são ignoradas.
  • A execução vai para as instruções na seção on-error.

Ao colocar instruções de política na seção on-error, você pode:

  • Revisar o erro usando a propriedade context.LastError.
  • Inspecionar e personalizar a resposta de erro usando a política set-body.
  • Configure no caso de ocorrer um erro.

Para obter mais informações, consulte Tratamento de erros em políticas de gerenciamento de API.

Expressões de política

A menos que a política especifique o contrário, as expressões de política podem ser usadas como valores de atributo ou texto em qualquer uma das políticas de Gerenciamento de API. A expressão de política é:

  • uma única instrução C# em @(expression) ou
  • um bloco de códigos C# de várias instruções, em @{expression} que retorna um valor

Cada expressão tem acesso à variável context fornecida implicitamente e a um subconjunto permitido de tipos de .NET Framework.

As expressões de política fornecem um meio sofisticado para controlar o tráfego e modificar o comportamento da API sem exigir que você escreva um código especializado ou modifique serviços de back-end. Algumas políticas são baseadas em expressões de políticas, como Fluxo de controle e Definir variável.

Escopos

O Gerenciamento de API permite definir políticas nos seguintes escopos, do mais amplo ao mais restrito:

  • Global (todas as APIs)
  • Workspace (todas as APIs associadas a um workspace selecionado)
  • Produto (todas as APIs associadas a um produto selecionado)
  • API (todas as operações em uma API)
  • Operação (operação única em uma API)

Para começar a configurar uma política, você deve primeiro selecionar o escopo ao qual ela se aplica.

Escopos de política

Observações importantes

  • Para ter um controle refinado para diferentes consumidores de API, você pode configurar definições de política em mais de um escopo

  • Nem todas as políticas têm suporte em cada seção de escopo e política

  • Ao configurar definições de política em mais de um escopo, você controla a herança da política e a ordem de avaliação da política em cada seção de política por meio da colocação do elemento base

  • As políticas aplicadas às solicitações de API também são afetadas pelo contexto da solicitação, incluindo a presença ou ausência de uma chave de assinatura usada na solicitação, o escopo da API ou do produto da chave de assinatura e se a API ou o produto requer uma assinatura.

    Observação

    Se você estiver usando uma assinatura com escopo de API, uma assinatura de todas as APIs ou a assinatura interna de todos os acessos, as políticas configuradas no escopo do produto não serão aplicadas a solicitações dessa assinatura.

Para saber mais, veja:

Políticas de resolvedor do GraphQL

Em Gerenciamento de API, um Resolvedor do GraphQL é configurado usando políticas com escopo para um tipo e campo específico de operação em um esquema de GraphQL.

  • Atualmente, o API Management tem suporte para resolvedores GraphQL que especificam fontes de dados de API HTTP, Cosmos DB ou Azure SQL. Por exemplo, configure uma única política http-data-source com elementos para especificar uma solicitação (e, opcionalmente, uma resposta) a uma fonte de dados HTTP.
  • Você não pode incluir uma política de resolvedor em definições de políticas em outros escopos como API, produto, ou todas as APIs. Também não herda políticas configuradas em outros escopos.
  • O gateway avalia uma política no escopo do resolvedor após qualquer política configurada inbound e backend políticas no pipeline de execução de políticas.

Para obter mais informações, consulte Configurar um resolvedor do GraphQL.

Obter assistência para criar políticas usando o Microsoft Copilot no Azure (versão prévia)

O Microsoft Copilot no Azure (versão prévia) oferece funcionalidades de criação de políticas para o Gerenciamento de API do Azure. Use o Copilot no Azure no contexto do editor de políticas do Gerenciamento de API para criar políticas que correspondam aos seus requisitos específicos sem conhecer a sintaxe ou ver a explicação de políticas já configuradas.

Você pode solicitar ao Copilot no Azure que gere definições de política, copiar os resultados no editor de políticas e fazer os ajustes necessários. Faça perguntas para obter informações sobre diferentes opções, modificar a política fornecida ou esclarecer a política que você já tem. Saiba mais

Exemplos

Aplicar políticas especificadas a escopos diferentes

Se você tiver uma política em nível global e uma política configurada para uma API, ambas as políticas poderão ser aplicadas sempre que essa API em particular for usada. O Gerenciamento de API permite uma ordenação determinística de instruções de política combinadas por meio do elemento base.

Definição de política de exemplo no escopo da API:

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

Na definição de política de exemplo acima:

  • A instrução cross-domain seria executada primeiro.
  • A política find-and-replace seria executada após qualquer política em um escopo mais amplo.

Observação

Se você remover o elemento base no escopo da API, somente as políticas configuradas no escopo da API serão aplicadas. Nem as políticas de produto nem as de escopo global seriam aplicadas.

Usar expressões de política para modificar solicitações

O exemplo a seguir usa expressões de política e a política set-header para adicionar dados do usuário à solicitação de entrada. O cabeçalho adicionado inclui a ID do usuário associada à chave de assinatura na solicitação e a região em que o gateway que está processando a solicitação está hospedado.

<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>

Conteúdo relacionado

Para obter mais informações sobre como trabalhar com políticas, consulte: