Políticas na Gestão de API do Azure

  • Artigo

APLICA-SE A: Todas as camadas de 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 uma coleção de instruções que são executadas sequencialmente no pedido ou na resposta de uma API. O Gerenciamento de API fornece mais de 50 políticas prontas para uso que você pode configurar 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, veja Gestão de API referência de política.

As políticas populares incluem:

  • Formatar a conversão de XML para JSON
  • Limitação da taxa de chamadas para restringir o número de chamadas recebidas de um programador
  • Filtrar pedidos provenientes de determinados endereços IP

As políticas são aplicadas dentro do gateway entre o consumidor da API e a API gerida. Enquanto o gateway recebe pedidos e os reencaminha, sem alterações, para a API subjacente, uma política pode aplicar alterações ao pedido de entrada e à resposta de saída.

Noções básicas sobre a configuração da política

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 definições de política, o portal fornece estas opções:

  • Um editor guiado baseado em formulários para simplificar a configuração de políticas populares sem codificar XML
  • Um editor de código onde você pode inserir trechos 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 em inbound, backend, outbounde on-error seções. Esta série de declarações de política especificadas é executada 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ítica, consulte API Management policy snippets repo.

Processamento de erros

Se ocorrer um erro durante o processamento de um pedido:

  • Todas as etapas restantes nas inboundseções , backendou outbound são ignoradas.
  • A execução salta para as instruções na on-error seção.

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

  • Revise o erro usando a context.LastError propriedade.
  • Inspecione e personalize a resposta de erro usando a set-body política.
  • Configure o que acontece se 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 valores de texto em qualquer uma das políticas de Gerenciamento de API. Uma expressão política é:

  • uma única instrução C# incluída no @(expression), ou
  • um bloco de código C# com várias instruções, incluído no @{expression}, que retorna um valor

Cada expressão tem acesso à variável implicitamente fornecida context e a um subconjunto permitido de tipos do .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 código especializado ou modifique serviços de back-end. Algumas políticas são baseadas em expressões de política, como Fluxo de controle e Variável set.

Âmbitos

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

  • Global (todas as APIs)
  • Espaço de trabalho (todas as APIs associadas a um espaço de trabalho 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)

Ao configurar uma política, você deve primeiro selecionar o escopo no qual a política se aplica.

Âmbitos das políticas

Aspetos importantes

  • Para 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 são suportadas em cada escopo e seção de política

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

  • 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, a API ou o escopo do produto da chave de assinatura e se a API ou o produto requer uma assinatura.

    Nota

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

Para obter mais informações, consulte:

Políticas do resolvedor GraphQL

No Gerenciamento de API, um resolvedor GraphQL é configurado usando políticas com escopo para um tipo de operação e campo específicos em um esquema GraphQL.

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

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

Obtenha assistência para criar políticas usando o Microsoft Copilot para Azure (visualização)

O Microsoft Copilot para Azure (visualização) fornece recursos de criação de políticas para o Gerenciamento de API do Azure. Use o Copilot para 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 já ter configurado políticas explicadas para você.

Você pode solicitar que o Copilot para Azure gere definições de política e, em seguida, copie os resultados para o editor de políticas e faça 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. Mais informações

Importante

O Microsoft Copilot para Azure (pré-visualização) requer registo e está atualmente disponível apenas para clientes e parceiros empresariais aprovados. Para obter mais informações, consulte Acesso limitado ao Microsoft Copilot para Azure (visualização).

Exemplos

Aplicar políticas especificadas em 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 específica for usada. O Gerenciamento de API permite a ordenação determinística de declarações de política combinadas por meio do base elemento .

Exemplo de definição de política no escopo da API:

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

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

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

Nota

Se você remover o base elemento no escopo da API, somente as políticas configuradas no escopo da API serão aplicadas. Nem as políticas de produto nem as políticas de âmbito 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 para adicionar dados do set-header usuário à solicitação de entrada. O cabeçalho adicionado inclui o ID de usuário associado à chave de assinatura na solicitação e a região onde o gateway que processa 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údos relacionados

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