Políticas do Gerenciamento de API do Azure

No Gerenciamento de API do Azure, os editores de API podem alterar o comportamento da API por meio da configuração usando 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. Veja algumas instruções populares:

  • Conversão de formato de XML para JSON.
  • Limitação de fluxo de chamadas para restringir o número de chamadas recebidas de um desenvolvedor.

Muitas políticas estão disponíveis pré-configuradas.

As políticas são aplicadas dentro do gateway que fica entre o consumidor da API e a API gerenciada. Enquanto o gateway recebe solicitações e as encaminha, inalteradas, para a API subjacente, uma política pode aplicar alterações à solicitação de entrada e à resposta de saída.

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. Algumas políticas baseiam-se em expressões de políticas, como Controlar fluxo e Definir variável. Para obter mais informações, confira os artigos Políticas avançadas e Expressões de política.

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 de entrada e saída. Você pode editar o XML diretamente na janela de definição, que também fornece:

  • Uma lista de instruções à direita.
  • As instruções aplicáveis ao escopo atual estão habilitadas e realçadas.

Clicar em uma instrução habilitada adicionará o XML adequado onde estiver o cursor na exibição de definição.

Observação

Se a política que deseja adicionar não estiver habilitada, verifique se você está no escopo correto para essa política. Cada declaração de política é projetada para uso em determinados escopos e seções de política. Para examinar as seções da política e os escopos de uma política, verifique a seção Uso em Referência à política.

A configuração é dividida em inbound, backend, outbound e on-error. Essa série de instruções de política especificadas é executada ordenadamente para uma solicitação e uma resposta.

<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 is an error condition go here -->
  </on-error>
</policies> 

Se ocorrer um erro durante o processamento de uma solicitação:

  • Todas as etapas restantes nas seções inbound, backend ou outbound 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:

  • Revisar o erro usando a propriedade context.LastError.
  • Inspecionar e personalizar a resposta de erro usando a política set-body.
  • Configure no caso de ocorrer um erro.

Para obter mais informações, confira Tratamento de erros em políticas de Gerenciamento de API para os códigos de erro de:

  • Etapas integradas
  • Erros que podem ocorrer durante o processamento de instruções de política.

Como configurar políticas

Para obter informações sobre como configurar as políticas, confira Definir ou editar políticas.

Referência de política

Consulte a Referência de política para ver uma lista completa das instruções de política e suas configurações.

Exemplos de política

Consulte em Exemplos de política mais exemplos de código.

Exemplos

Aplicar políticas especificadas a escopos diferentes

Se você tiver uma política a nível global e uma política configurada para uma API, ambas as políticas serão 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.

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

Na definição de política de exemplo acima:

  • A instrução cross-domain seria executada antes de qualquer política superior.
  • A política find-and-replace seria executada antes de qualquer política superior.

Observação

Se você remover a marca <base /> no escopo da API, somente as políticas configuradas no escopo da API serão aplicadas. Nem as políticas de produto nem as de escopo global seriam aplicadas.

Restringir as solicitações de entrada

Para adicionar uma nova instrução para restringir as solicitações de entrada a endereços IP especificados, posicione o cursor dentro do conteúdo do elemento XML inbound e clique na instrução inbound.

Políticas de restrição

Isto adicionará um snippet XML ao elemento inbound que fornecerá diretrizes de como configurar a instrução.

<ip-filter action="allow | forbid">
    <address>address</address>
    <address-range from="address" to="address"/>
</ip-filter>

Para limitar as solicitações de entrada e aceitar somente as provenientes de um endereço IP 1.2.3.4, modifique o XML da seguinte forma:

<ip-filter action="allow">
    <address>1.2.3.4</address>
</ip-filter>

Próximas etapas

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