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

Este artigo mostra-lhe como configurar políticas na sua instância de Gestão de API ao editar 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 num pedido e resposta de API.

O editor de políticas no portal fornece formulários orientados para os publicadores de API adicionarem e editarem políticas nas definições de políticas. Também pode editar o XML diretamente no editor de código de política.

Mais informações sobre políticas:

• Descrição geral da política
• Referência de política para uma lista completa de declarações de política e respetivas definições
• Exemplos de Políticas

Pré-requisitos

Se ainda não tiver uma instância Gestão de API e uma API de back-end, veja:

• crie uma instância da Gestão de API do Azure
• Importar e publicar uma API

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

1. Na portal do Azure, procure e selecione Gestão de API serviços.

   

2. Na página Gestão de API serviços, selecione a sua instância Gestão de API.

   

Configurar a política no portal

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

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

Neste exemplo, a política filtra os pedidos de determinados endereços IP recebidos. Está no âmbito de uma API selecionada.

Nota

Pode configurar políticas noutros âmbitos, como para todas as APIs, um produto ou uma única operação de API. Veja Configurar âmbito, mais adiante neste artigo, para obter outros exemplos.

Para configurar uma política:

Formulário

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

2. Selecione uma API que 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 secção Processamento de entrada , selecione + Adicionar política.

   

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

   

   Dica

   • As políticas apresentadas estão confinadas à secção de política que está a configurar, neste caso, para processamento de entrada.
   • Se não vir uma política pretendida, selecione o mosaico Outras políticas . Esta ação irá abrir o editor de código XML e apresentar uma lista completa de políticas para essa secção e âmbito.

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

   

8. Selecione Guardar para propagar imediatamente as alterações ao gateway de Gestão de API.

   A política de filtro ip é agora apresentada na secção Processamento de entrada .

Código

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

2. Selecione uma API que 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 secção Processamento de entrada , selecione o <ícone /> (editor de código).

   

6. Para ver os fragmentos de código XML da política disponível, selecione Mostrar fragmentos. Por exemplo, selecione Restringir IPs do autor da chamada.

   

7. Cole ou introduza o fragmento de código de política pretendido num dos blocos adequados 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 subordinados e os elementos subordinados de uma política na ordem fornecida na declaração de política.

8. Selecione Guardar para propagar imediatamente as alterações ao gateway de Gestão de API.

   A política de filtro ip é agora apresentada na secção Processamento de entrada .

Configurar políticas em diferentes âmbitos

Gestão de API dá-lhe flexibilidade para configurar definições de política em vários âmbitos, em cada uma das secções de política.

Importante

Nem todas as políticas podem ser aplicadas em cada secção de âmbito ou 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 de política e os âmbitos de uma política, verifique a secção Utilização nos tópicos De referência de política .

Nota

A secção Política de back-end só pode conter um elemento de política. Por predefinição, Gestão de API configura a forward-request política na secção Back-end no âmbito global e o base elemento noutros âmbitos.

Âmbito global

O âmbito global está configurado para Todas as APIs na sua instância de Gestão de API.

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

2. Selecione o separador Design.

   

3. Numa secção de política, selecione + Adicionar política para utilizar um editor de políticas baseado em formulários ou selecione o <ícone /> (editor de código) para adicionar e editar XML diretamente.

4. Selecione Guardar para propagar imediatamente as alterações ao gateway de Gestão de API.

Âmbito do produto

O âmbito do produto está 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. Numa secção de política, selecione + Adicionar política para utilizar um editor de políticas baseado em formulários ou selecione o <ícone /> (editor de código) para adicionar e editar XML diretamente.

4. Selecione Guardar para propagar imediatamente as alterações ao gateway de Gestão de API.

Âmbito da API

O âmbito da API está configurado para Todas as operações da API selecionada.

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

2. Selecione o separador Design.

3. Selecione Todas as operações.

   

4. Numa secção de política, selecione + Adicionar política para utilizar um editor de políticas baseado em formulários ou selecione o <ícone /> (editor de código) para adicionar e editar XML diretamente.

5. Selecione Guardar para propagar imediatamente as alterações ao gateway de Gestão de API.

Âmbito da operação

O âmbito da operação está configurado para uma operação de API selecionada.

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

2. Selecione o separador Design.

3. Selecione a operação à qual pretende aplicar políticas.

   

4. Numa secção de política, selecione + Adicionar política para utilizar um editor de políticas baseado em formulários ou selecione o <ícone /> (editor de código) para adicionar e editar XML diretamente.

5. Selecione Guardar para propagar as alterações ao gateway de Gestão de API imediatamente.

Reutilizar configurações de políticas

Pode criar fragmentos de política reutilizáveis na instância Gestão 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-no a configurar políticas de forma consistente e a manter as definições de política sem ter de repetir ou escrever novamente código XML.

Utilize a include-fragment política para inserir um fragmento de política numa definição de política.

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

Se configurar definições de políticas em mais do que um âmbito, podem ser aplicadas múltiplas políticas a um pedido ou resposta de API. Consoante a ordem pela qual as políticas dos diferentes âmbitos são aplicadas, a transformação do pedido ou resposta pode ser diferente.

Em Gestão de API, determine a ordem de avaliação da política por colocação do base elemento em cada secção na definição de política em cada âmbito. O base elemento herda as políticas configuradas nessa secção no próximo âmbito mais amplo (principal). O base elemento está incluído por predefinição em cada secção de política.

Nota

Para ver as políticas efetivas no âmbito atual, selecione Calcular política efetiva no editor de políticas.

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

1. Comece com a definição no âmbito mais estreito que configurou, que Gestão de API será aplicado primeiro.

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

2. Coloque o base elemento numa secção para determinar onde herdar todas as políticas da secção correspondente no âmbito principal.

   Por exemplo, numa inbound secção configurada no âmbito da API, coloque um base elemento para controlar onde herdar políticas configuradas na inbound secção no âmbito global. No exemplo seguinte, as políticas herdadas do âmbito 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

   • Pode colocar o base elemento antes ou depois de qualquer elemento de política numa secção.
   • Se quiser impedir a herdação de políticas do âmbito principal, remova o base elemento. Na maioria dos casos, isto não é recomendado.

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

   Uma política de âmbito global não tem âmbito principal e a utilização do base elemento na mesma não tem qualquer efeito.

Passos seguintes

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 para uma lista completa de declarações de política e respetivas definições
• Exemplos de Políticas