Escolher a política de Gerenciamento de API correta
É possível usar as políticas de Gerenciamento de API para controlar o comportamento de uma API implantada sem reescrever seu código.
Na empresa de jogos de tabuleiro, você tem um conjunto de APIs que permitem que organizações parceiras obtenham estimativas de preço, que os membros da equipe verifiquem os níveis de estoque e que os clientes façam pedidos. Você quer resolver um problema específico de desempenho e investigar o que mais é possível obter com as políticas.
Primeiro, vamos ver o que você pode fazer com as políticas.
Quais são as políticas?
No Gerenciamento de API do Azure, os administradores podem usar políticas para alterar o comportamento das APIs por meio da configuração. O comportamento e a funcionalidade principais de uma API são projetados pelos desenvolvedores que escrevem o código. No entanto, os administradores podem usar políticas para definir limites, converter formatos de resposta ou impor requisitos de segurança. Neste módulo, o foco será o uso de políticas para configurar e controlar um cache.
As políticas são compostas por instruções individuais, que são executadas em ordem. Os documentos da política são estruturas XML que contém elementos que podem ser usados para controlar o comportamento da API.
Quando as políticas são executadas?
No Gerenciamento de API do Azure, as políticas são executadas quatro vezes:
- Entrada: essas políticas são executadas quando uma solicitação é recebida de um cliente.
- Back-end: essas políticas são executadas antes de uma solicitação ser encaminhada para uma API gerenciada.
- Saída: essas políticas são executadas antes de uma resposta ser enviada para um cliente.
- Em caso de erro: essas políticas são executadas quando uma exceção é gerada.
No XML da política, há uma tag separada para cada um desses tempos de execução:
<policies>
<inbound>
<base />
<check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
</check-header>
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
<json-to-xml apply="always" consider-accept-header="false" parse-date="false" />
</outbound>
<on-error>
<base />
</on-error>
</policies>
Neste exemplo, você pode ver que a política verifica as solicitações recebidas de um cabeçalho chamado Autorização. Se esse cabeçalho não estiver presente, a política exibirá uma mensagem de erro.
Esta política também converte todas as respostas de saída no formato JSON em XML.
Escopos de política
O escopo de uma política determina a abrangência de sua aplicação. Veja os seguinte escopos de política que podem ser escolhidos:
- Global
- Produto
- API
- Operação
Global
As políticas aplicadas o escopo global afetam todas as APIs na instância do Gerenciamento de API.
Para usar o escopo global, no painel de serviço de Gerenciamento de API, no painel do menu à esquerda, em Gerenciamento de API, selecione APIs e selecione Todas as APIs no painel do menu central. Selecione + Adicionar política na seção Processamento de entrada ou Processamento de saída para exibir as políticas que podem ser adicionados no escopo.
Escolha uma das opções disponíveis para iniciar um assistente que fornecerá orientações para que você adicione a política com a sintaxe correta:
Também é possível abrir o editor de XML diretamente selecionando o símbolo de marca </> nas seções Processamento de entrada, Processamento de saída ou Back-end. O editor de política exibido tem conteúdo XML padrão. À direita, selecione Mostrar snippets para encontrar atalhos que adicionam políticas:
Produto
No Gerenciamento de API, é possível juntar uma ou mais APIs em um único produto e, em seguida, gerenciar o acesso a esse produto como uma entidade única. As políticas aplicadas ao escopo do produto afetam todas as APIs nesse produto. As APIs de outros produtos não são afetadas. Ao gerenciar um produto no portal do Azure, selecione o painel Políticas para adicionar políticas por meio de um assistente guiado ou usando o editor de política XML:
API
As políticas aplicadas ao escopo da API afetam somente uma única API. Para definir uma política no escopo da API, na home page do Gerenciamento de API, selecione APIs e a API que você deseja gerenciar. Por fim, na guia Design, selecione Todas as operações. É possível definir políticas de entrada, saída ou back-end que se aplicam a todas as operações nessa API:
Operação
As políticas aplicadas ao escopo da operação afetam somente uma operação dentro API. No exemplo abaixo, o administrador selecionou a operação GetSpeaker na API de Conferência de Demonstração e pode definir políticas de entrada, saída ou back-end que se aplicam somente a essa operação:
Em que ordem as políticas são aplicadas?
É possível usar a tag <base /> para determinar quando as políticas de um escopo mais elevado serão aplicadas. Por exemplo, considere esta política, aplicada ao escopo da API:
<policies>
<inbound>
<base />
<find-and-replace from="game" to="board game" />
</inbound>
</policies>
Como a marca <base> aparece acima da marca <find-and-replace>, o Gerenciamento de API do Azure aplica primeiro as políticas dos escopos global e de produto e, em seguida, executa a política de localizar e substituir.
Políticas comumente usadas
Vamos examinar o que você pode fazer com as políticas no Gerenciamento de API. Você verá a seguir algumas das políticas mais usadas, mas é possível visitar a documentação do Gerenciamento de API para obter uma lista completa e exemplos.
Políticas para restringir o acesso
Há diversas políticas que podem ser usadas para impedir ou limitar o acesso a uma API ou às operações dela. Por exemplo:
Use a política Verificar cabeçalho HTTP para verificar uma propriedade em um cabeçalho HTTP. Se a propriedade não for encontrada, o Gerenciamento de API do Azure removerá a solicitação.
A política Limitar a taxa de chamadas por assinatura restringe o número de chamadas que podem vir de uma única assinatura de API. Essa política pode garantir que os usuários de uma assinatura não usem toda a sua largura de banda.
Se você quiser restringir o número de chamadas recebidas com uma chave de acesso único, use a política Limitar taxa de chamadas por chave.
Para permitir ou recusar chamadas de endereços IP ou intervalos específicos, use a política Restringir IPs do chamador. Essa forma de restringir o acesso se comporta como as restrições de endereço IP que você pode aplicar em um firewall.
Políticas para autenticação
Diversas políticas permitem que você controle a autenticação. Por exemplo:
Use a política Autenticar com o Básico para habilitar a autenticação em texto sem formatação. Essa forma de autenticação é amplamente compatível. No entanto, lembre-se de que ela precisa ser protegida com criptografia SSL; caso contrário, um ataque mal-intencionado poderá interceptar as credenciais quando elas passarem pela rede.
Use a política Autenticar com o certificado de cliente para habilitar os clientes a autenticar fornecendo um certificado do cliente.
Políticas entre domínios
As solicitações entre domínios são consideradas uma ameaça de segurança e recusadas por navegadores e APIs. No entanto, para operações específicas, elas podem ser desejáveis e as políticas de Gerenciamento de API permitem que elas sejam habilitadas de uma forma segura.
Use a política Permitir chamadas entre domínios para permitir chamadas do Adobe Flash e do Silverlight. Se a API ou os aplicativos cliente dependerem do CORS (Compartilhamento de Recursos entre Origens), use a política do CORS para permiti-las.
Uma parte do código AJAX, que é executado no navegador, usa JSON com preenchimento para fazer chamadas entre domínios com segurança. Use a política JSONP para permitir que os clientes usem essa técnica.
Políticas de transformação
Geralmente, é útil alterar o formato ou o conteúdo de uma resposta de uma API gerenciada. É possível fazer isso com diversas políticas. Por exemplo:
Para converter entre JSON e XML, use as políticas Converter JSON para XML e Converter XML para JSON. Essas políticas geralmente ajudam a transformar diversas APIs em um produto consistente. Com elas, também não é preciso recodificar uma API quando um aplicativo espera uma resposta em um formato específico.
Às vezes, você quer manter a resposta em XML, mas alterar o esquema. Nesses casos, use a política Transformar XML para aplicar um modelo XSLT.
Use Localizar e substituir cadeia de caracteres no corpo para substituir uma cadeia de caracteres. Por exemplo, se o nome da marca tiver sido alterado, você poderá usar esta política para garantir que a alteração seja refletida em todas as respostas, mesmo se os dados subjacentes ainda incluírem referências ao nome antigo.
A política Mascarar URLs no conteúdo pode reescrever quaisquer links no corpo da resposta de modo que eles apontem para uma localização diferente. Esta política é útil quando um site ou API Web é movido.
Use a política Definir corpo para definir o texto da mensagem de solicitações recebidas e enviadas.
Se você quiser modificar uma solicitação HTTP recebida ou uma resposta enviada, poderá usar várias políticas diferentes. Para adicionar itens a uma resposta ou cabeçalho de solicitação existente, use a política Definir cabeçalho HTTP. Se você precisar modificar as cadeias de caracteres de consulta, que aparecem após o sinal de interrogação na URL, use a política Definir parâmetro de cadeia de caracteres de consulta. Se uma URL pública, solicitada por um usuário, precisar ser mapeada para um destino interno diferente, a política Reescrever URL poderá executar a conversão tanto na entrada quanto na saída.
Políticas avançadas
Essas políticas podem ser usadas em cenários em que você deseja um comportamento não padrão.
Por exemplo, se você quiser aplicar uma política somente quando a resposta passa um teste específico, use a política Controlar fluxo.
Use a política Encaminhar solicitação para encaminhar uma solicitação para um servidor de back-end.
Para controlar o que acontece quando uma ação falha, use a política de Repetição. As instruções de política incluídas na repetição serão executadas repetidamente até que uma condição seja atendida. A execução será repetida em intervalos de tempo especificados até que o valor de contagem de repetições seja alcançado.
A política Enviar solicitação unidirecional pode enviar uma solicitação para a URL sem aguardar uma resposta.
Se você quiser armazenar um valor para uso em um cálculo ou teste posterior, use a política Definir variável para persistir um valor em uma variável nomeada.