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 declarações de política e suas configurações
• Recompra de trechos de política
• Kit de ferramentas de política de 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:

• 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 Gerenciamento de API.

   

2. Na página 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.

Nota

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

Para configurar uma política:

Formulário

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

2. Selecione uma API que você importou anteriormente.

3. Selecione o separador 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 para adicionar. Por exemplo, selecione Filtrar endereços IP.

   

   Gorjeta

   • As políticas mostradas têm como escopo a seção de política que você está configurando - neste caso, para processamento de entrada.
   • Se não vir uma política pretendida, selecione o mosaico 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 o ú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 as alterações para o gateway de Gerenciamento de API imediatamente.

   A política de filtro ip agora aparece na seção Processamento de entrada.

Código

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

2. Selecione uma API que você importou anteriormente.

3. Selecione o separador 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 trechos de código XML de política disponíveis, selecione Mostrar trechos. Por exemplo, selecione Restringir IPs do chamador.

   

7. Cole ou insira o trecho 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>
   

   Nota

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

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

   A política de filtro ip agora aparece na seção Processamento de entrada.

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.

Importante

Nem todas as políticas podem ser aplicadas em cada escopo ou seção de política. Se a política que pretende adicionar não estiver ativada, certifique-se de que está numa secção de política suportada e no âmbito dessa política. Para rever as secções e âmbitos de política de uma política, verifique a secção Utilização nos tópicos de referência da política.

Nota

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

Â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 para inserir um fragmento include-fragment 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 próximo escopo mais amplo (pai). O base elemento é incluído por padrão em cada seção de política.

Nota

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

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 base elemento dentro de uma seção para determinar onde herdar todas as políticas da seção correspondente no escopo pai.

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

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

   Nota

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

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 usar o base elemento nela não tem efeito.

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

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

Você pode solicitar que o Copilot no 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

Conteúdos relacionados

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íticas
• Recompra de trechos de política
• Kit de ferramentas de política de Gerenciamento de API do Azure
• Criar políticas usando o Microsoft Copilot no Azure