Como definir ou editar as políticas de Gestão de API do Azure

APLICA-SE A: Todas as camadas de gerenciamento de API

Este artigo mostra como configurar políticas em sua instância de Gerenciamento de API editando definições de política no portal do Azure. Cada definição de política é um documento XML que descreve uma sequência de instruções de entrada e saída que são executadas sequencialmente em uma solicitação e resposta de API.

O editor de políticas no portal fornece formulários guiados para editores de API adicionarem e editarem políticas em definições de política. Você também pode editar o XML diretamente no editor de código de política.

Mais informações sobre políticas:

• Visão geral da política
• Referência de Política para uma lista completa de políticas e suas configurações
• Repositório de trechos de política
• Kit de ferramentas de política de Gerenciamento de API do Azure
• Políticas de autor usando o Azure Copilot

Pré-requisitos

Se você ainda não tiver uma instância de Gerenciamento de API e uma API de back-end, consulte:

• crie uma instância da Gestão de API do Azure
• Importe e publique uma API

Vá para a sua instância de Gestão de API

1. No Portal do Azure , procure e selecione Serviços de Gestão de API:

   

2. Na página de serviços de Gerenciamento de API, selecione sua instância de Gerenciamento de API:

   

Configurar política no portal

O exemplo a seguir mostra como configurar uma política usando duas opções no editor de políticas no portal:

• Um editor guiado baseado em formulários para simplificar a configuração de muitas políticas
• Um editor de código onde você pode adicionar ou editar XML diretamente

Neste exemplo, a política filtra solicitações de determinados endereços IP de entrada. Tem como escopo uma API selecionada.

Para configurar uma política:

Configurar políticas em escopos diferentes

O Gerenciamento de API oferece flexibilidade para configurar definições de política em vários escopos, em cada uma das seções de política.

Âmbito global

O escopo global é configurado para Todas as APIs em sua instância de Gerenciamento de API.

1. Na navegação à esquerda da sua instância de Gerenciamento de API, selecione APIs>Todas as APIs.

2. Selecione o separador Design.

   

3. Em uma seção de política, selecione + Adicionar política para usar um editor de política baseado em formulário ou selecione o ícone </> (editor de código) para adicionar e editar XML diretamente.

4. Selecione Salvar para propagar as alterações para o gateway de Gerenciamento de API imediatamente.

Âmbito do produto

O escopo do produto é configurado para um produto selecionado.

1. No menu esquerdo, selecione Produtos e, em seguida, selecione um produto ao qual pretende aplicar políticas.

2. Na janela do produto, selecione Políticas.

   

3. Em uma seção de política, selecione + Adicionar política para usar um editor de política baseado em formulário ou selecione o ícone </> (editor de código) para adicionar e editar XML diretamente.

4. Selecione Salvar para propagar as alterações para o gateway de Gerenciamento de API imediatamente.

Âmbito da API

O escopo da API é configurado para Todas as operações da API selecionada.

1. Na navegação à esquerda da sua instância de Gerenciamento de API, selecione APIs e, em seguida, selecione a API à qual você deseja aplicar políticas.

2. Selecione o separador Design.

3. Selecione Todas as operações.

   

4. Em uma seção de política, selecione + Adicionar política para usar um editor de política baseado em formulário ou selecione o ícone </> (editor de código) para adicionar e editar XML diretamente.

5. Selecione Salvar para propagar as alterações para o gateway de Gerenciamento de API imediatamente.

Âmbito da operação

O escopo da operação é configurado para uma operação de API selecionada.

1. Na navegação à esquerda da instância de Gerenciamento de API, selecione APIs.

2. Selecione o separador Design.

3. Selecione a operação à qual você deseja aplicar políticas.

   

4. Em uma seção de política, selecione + Adicionar política para usar um editor de política baseado em formulário ou selecione o ícone </> (editor de código) para adicionar e editar XML diretamente.

5. Selecione Salvar para propagar as alterações para o gateway de Gerenciamento de API imediatamente.

Reutilizar configurações de política

Você pode criar fragmentos de política reutilizáveis em sua instância de Gerenciamento de API. Os fragmentos de política são elementos XML que contêm as configurações de uma ou mais políticas. Os fragmentos de política ajudam a configurar políticas de forma consistente e a manter as definições de política sem a necessidade de repetir ou redigitar o código XML.

Use a política include-fragment para inserir um fragmento de política em uma definição de política.

Use base o elemento para definir a ordem de avaliação da política

Se você configurar definições de política em mais de um escopo, várias políticas poderão ser aplicadas a uma solicitação ou resposta de API. Dependendo da ordem em que as políticas dos diferentes escopos são aplicadas, a transformação da solicitação ou resposta pode ser diferente.

No Gerenciamento de API, determine a ordem de avaliação da política pelo posicionamento do base elemento em cada seção da definição de política em cada escopo. O base elemento herda as políticas configuradas nessa seção no escopo imediatamente superior (pai). O base elemento é incluído por padrão em cada seção de política.

Para modificar a ordem de avaliação da política usando o editor de políticas:

1. Comece com a definição no escopo mais restrito que você configurou, qual Gerenciamento de API será aplicado primeiro.

   Por exemplo, ao usar definições de política configuradas no escopo global e no escopo da API, comece com a configuração no escopo da API.

2. Coloque o elemento base dentro de uma seção para determinar onde herdar todas as políticas da seção correspondente no escopo pai.

   Por exemplo, numa inbound seção configurada no escopo da API, coloque um elemento base para controlar onde herdar as políticas configuradas numa inbound seção no escopo global. No exemplo a seguir, as políticas herdadas do escopo global são aplicadas antes da política ip-filter.

   <policies>
     <inbound>
         <base />
           <ip-filter action="allow">
               <address>10.100.7.1</address>
           </ip-filter>
     </inbound>
     [...]
   </policies>
   

   Nota

   • Você pode colocar o elemento base antes ou depois de qualquer elemento de política em uma seção.
   • Se quiser impedir a herança de políticas do escopo pai, remova o elemento base. Na maioria dos casos, isso não é recomendado. No entanto, ele pode ser útil em determinadas situações, como quando você deseja aplicar políticas diferentes a uma operação específica do que as configuradas para o escopo da API (todas as operações).

3. Continue a configurar o base elemento em definições de política em escopos sucessivamente mais amplos.

   Uma política com escopo global não tem escopo pai, e o uso do elemento base nela não tem efeito.

Obtenha a 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. 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 Azure Copilot fornece assistência na criação de políticas com prompts em linguagem natural no portal 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íticas.
• O GitHub Copilot para Azure no Visual Studio Code fornece assistência de criação de políticas 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 da política. Você pode solicitar o Copilot Chat ou o Copilot Edits com linguagem natural para criar e refinar as definições de política em vigor.

Exemplo de prompt:

Generate a policy that adds an Authorization header to the request with a Bearer token.

O copiloto é alimentado por IA, por isso surpresas e erros são possíveis. Para obter mais informações, consulte Perguntas frequentes sobre o uso geral do Copilot.

Conteúdos relacionados

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

• Tutorial: Transforme e proteja sua API
• Referência de Política para uma lista completa de políticas e suas configurações
• Expressões de política
• Definir ou editar políticas
• Reutilizar configurações de políticas
• Repositório de trechos de política
• Política de recompra de parques infantis
• Kit de ferramentas de política de Gerenciamento de API do Azure
• Obtenha assistência do Copilot para criar, explicar e resolver problemas com políticas