Como definir ou editar políticas de Gerenciamento de API do Azure

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

Este artigo mostra como configurar políticas na 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 os 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.

Para saber mais sobre políticas:

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

Pré-requisitos

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

• Criar uma instância do Gerenciamento de API do Azure
• Importar e publicar uma API

Navegar até a instância de Gerenciamento de API

1. No portal do Azure, pesquise e selecione serviços de Gerenciamento de API.

   

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

   

Configurar a 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 baseado em formulário guiado para simplificar a configuração de muitas políticas
• Um editor de código em que você pode adicionar ou editar XML diretamente

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

Observação

Você pode configurar políticas em outros escopos, como para todas as APIs, um produto ou uma única operação de API. Consulte Configurar o escopo, abaixo, neste artigo, para outros exemplos.

Para configurar uma política:

Formulário

1. No painel de navegação esquerdo de sua instância do Gerenciamento de API, selecione APIs.

2. Selecione uma API que você tenha importado anteriormente.

3. Selecione a guia Design.

4. Para aplicar a política a todas as operações, selecione Todas as operações.

5. Na seção Processamento de entrada, selecione + Adicionar política.

   

6. Em Adicionar política de entrada, selecione uma política a ser adicionada. Por exemplo, selecione Filtrar endereços IP.

   

   Dica

   • As políticas mostradas têm como escopo a seção de políticas que você está configurando – nesse caso, para processamento de entrada.
   • Se você não vir uma política desejada, selecione o bloco Outras políticas. Isso abrirá o editor de código XML e exibirá uma lista completa de políticas para essa seção e escopo.

7. Selecione IPs permitidos>+ Adicionar filtro IP e adicione o primeiro e último endereços IP de um intervalo de endereços de entrada que têm permissão para fazer solicitações de API. Adicione outros intervalos de endereços IP, se necessário.

   

8. Selecione Salvar para propagar alterações no gateway de Gerenciamento de API imediatamente.

   Agora, a política de filtro ip aparece na seção Processamento de entrada.

Código

1. No painel de navegação esquerdo de sua instância do Gerenciamento de API, selecione APIs.

2. Selecione uma API que você tenha importado anteriormente.

3. Selecione a guia Design.

4. Para aplicar a política a todas as operações, selecione Todas as operações.

5. Na seção Processamento de entrada, selecione o ícone </> (editor de código).

   

6. Para ver os snippets de código XML de política disponíveis, selecione Mostrar snippets. Por exemplo, selecione Restringir IPs de chamador.

   

7. Cole ou insira o snippet de código de política desejado em um dos blocos apropriados e conclua a configuração da política.

   <policies>
       <inbound>
           <base />
           <ip-filter action="allow">
               <address-range from="10.100.7.0" to="10.100.127.0" />
           </ip-filter>
       </inbound>
       <backend>
           <base />
       </backend>
       <outbound>
           <base />
       </outbound>
       <on-error>
           <base />
       </on-error>
   </policies>
   

   Observação

   Defina os elementos e elementos filho de uma política na ordem fornecida na instrução de política.

8. Selecione Salvar para propagar alterações no gateway de Gerenciamento de API imediatamente.

   Agora, a política de filtro ip aparece na seção Processamento de entrada.

Configurar políticas em diferentes escopos

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

Importante

Nem todas as políticas podem ser aplicadas em cada seção de escopo ou política. Se a política que você deseja adicionar não estiver habilitada, verifique se você está em uma seção de política com suporte e no escopo correto para essa política. Para examinar as seções da política e os escopos de uma política, verifique a seção Uso nos tópicos de Referência à política.

Observação

A seção de política de back-end pode conter apenas um elemento de política. Por padrão, o Gerenciamento de API configura a política forward-request na seção Back-end no escopo global e o elemento base em outros escopos.

Escopo global

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

1. No painel de navegação esquerdo da sua instância de Gerenciamento de API, selecione APIs>Todas as APIs.

2. Selecione a guia 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 alterações no gateway de Gerenciamento de API imediatamente.

Escopo do produto

O escopo do produto é configurado para o produto selecionado.

1. No menu à esquerda, selecione Produtos e, em seguida, selecione um produto ao qual você deseja 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 alterações no gateway de Gerenciamento de API imediatamente.

Escopo de API

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

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

2. Selecione a guia 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 alterações no gateway de Gerenciamento de API imediatamente.

Escopo de operação

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

1. No painel de navegação esquerdo de sua instância do Gerenciamento de API, selecione APIs.

2. Selecione a guia Design.

3. Selecione a operação à qual 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 alterações no gateway de Gerenciamento de API imediatamente.

Reutilizar configurações de política

É possível 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 suas configurações de uma ou mais políticas. Eles ajudam a configurar políticas de maneira consistente e manter definições de política sem a necessidade de repetir ou digitar novamente o código XML.

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

Usar o elemento base para definir a ordem de avaliação de 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 diferir.

No Gerenciamento de API, determine a ordem de avaliação de política por posicionamento do elemento base em cada seção na definição de política em cada escopo. O elemento base herda as políticas configuradas nessa seção no próximo escopo mais amplo (pai). O elemento base é incluído por padrão em cada seção de política.

Observação

Para exibir as políticas efetivas no escopo atual, selecione Calcular a política efetiva no editor de políticas.

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

1. Comece com a definição no escopo mais estreito que você configurou, o qual o Gerenciamento de API aplicará 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, em uma seção inbound configurada no escopo da API, coloque um elemento base para controlar onde herdar políticas configuradas na seção inbound 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>
   

   Observação

   • Você pode colocar o elemento base antes ou depois de qualquer elemento de política em uma seção.
   • Se desejar impedir a ação de herdar políticas do escopo pai, remova o elemento base. Na maioria dos casos, isso não é recomendado.

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

   Uma política com escopo global não tem nenhum escopo pai e usar o elemento base nela não tem nenhum efeito.

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

Conteúdo relacionado

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

• Tutorial: Transformar e proteger APIs
• Definir ou editar políticas
• Referência de política
• Repositório de snippets de política
• Kit de ferramentas de políticas do Gerenciamento de API do Azure
• Criar políticas usando o Microsoft Copilot no Azure