Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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. Este artigo descreve como usar 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 75 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 taxa de chamada para restringir o número de chamadas recebidas de um desenvolvedor.
- Filtragem de solicitações 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. Embora o gateway receba solicitações e as encaminhe, sem alterações, 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
. Esta série de instruções de política especificadas é executada para uma solicitação e uma resposta. É assim que parece:
<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's an error condition go here -->
</on-error>
</policies>
Para obter exemplos de XML de políticas, consulte 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
ououtbound
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:
- Examine o erro usando a
context.LastError
propriedade. - Inspecione e personalize 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. Uma expressão de política é uma das seguintes:
- Uma única instrução C# encapsulada em
@(expression)
- Um bloco de código C# com várias instruções, entre
@{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ê grave 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 que você defina políticas nos seguintes escopos, apresentados aqui do mais amplo ao mais estreito:
- 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 (uma única operação em uma API)
Para começar a configurar uma política, você deve primeiro selecionar o escopo ao qual ela se aplica.
Observações 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 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 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, 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 obter mais informações, consulte:
Políticas do resolvedor do GraphQL
No Gerenciamento de API, um resolvedor GraphQL é configurado com políticas abrangendo um tipo de operação específico e campo em um esquema GraphQL.
- Atualmente, o Gerenciamento de API dá suporte a resolvedores do GraphQL que especificam fontes de dados HTTP, Azure Cosmos DB ou SQL do Azure. Por exemplo, você pode configurar uma única
http-data-source
política com elementos para especificar uma solicitação (e, opcionalmente, resposta de) uma fonte de dados HTTP. - Você não pode incluir uma política de resolvedor em definições de política em outros escopos, como API, produto ou todas as APIs. A política também não herda políticas configuradas em outros escopos.
- O gateway avalia uma política com escopo de resolvedor após qualquer política
inbound
ebackend
configurada no pipeline de execução da política.
Para obter mais informações, consulte Configurar um resolvedor do GraphQL.
Obter assistência do Copilot
Você pode obter assistência de IA do Copilot para criar e editar suas definições de política de Gerenciamento de API. Você pode usar o Copilot para criar e atualizar políticas que correspondam aos seus requisitos específicos sem precisar conhecer a sintaxe XML. Você também pode obter explicações sobre as políticas existentes. E o Copilot pode ajudá-lo a traduzir políticas que você pode ter configurado em outras soluções de gerenciamento de API.
- O Microsoft Copilot no Azure fornece assistência de criação de políticas com prompts de linguagem natural no portal do Azure. Você pode criar políticas no editor de políticas de Gerenciamento de API e pedir ao Copilot para explicar as seções de política.
- O GitHub Copilot para Azure no Visual Studio Code fornece assistência de criação de política no Visual Studio Code e você pode usar a Extensão de Gerenciamento de API do Azure para Visual Studio Code para acelerar a configuração de política. Você pode solicitar o Copilot Chat ou o Copilot Edits com linguagem natural para criar e refinar definições de políticas existentes.
Exemplo de solicitação:
Generate a policy that adds an Authorization header to the request with a Bearer token.
Copilot é alimentado pela IA, portanto, surpresas e erros são possíveis. Para obter mais informações, consulte perguntas frequentessobre uso geral do Copilot.
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 anterior:
- A
cross-domain
instrução é executada primeiro. - A política
find-and-replace
é 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. As políticas configuradas no produto e em escopos mais amplos não serão aplicadas.
Usar expressões de política para modificar solicitações
O exemplo a seguir usa expressões de política e a set-header
política para adicionar dados de usuário a solicitações 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 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údo relacionado
Para obter mais informações sobre como trabalhar com políticas, consulte:
- Tutorial: Transformar e proteger sua API
- Referência de Política para uma lista completa das instruções de política e suas configurações
- Expressões de política
- Definir ou editar políticas
- Reutilizar configurações de política
- Repositório de snippets de política
- Repositório de playground de políticas
- Kit de ferramentas de políticas do Gerenciamento de API do Azure
- Obter assistência do Copilot para criar, explicar e solucionar problemas de políticas