Chamar uma API com uma chave de subscrição
Ao publicar uma API, geralmente quer ter algum nível de controlo sobre quem pode aceder à API através do gateway. As chaves de assinatura são uma maneira de restringir o acesso a uma API.
Aqui, você aprende a usar chaves de assinatura para proteger suas APIs.
Subscrições e chaves
Para proteger as suas APIs, pode utilizar uma chave de subscrição.
Nota
Em ambientes de gerenciamento de API de produção, você normalmente combina uma chave de assinatura com outros mecanismos para proteger suas APIs contra uso não autorizado, como autenticação de certificado ou autorização OAuth 2.0. Estes estão fora do âmbito deste módulo.
Uma chave de assinatura é uma cadeia de caracteres gerada automaticamente exclusiva, que é passada nos cabeçalhos da solicitação do cliente ou como uma cadeia de caracteres de consulta na URL. A chave está diretamente relacionada a uma assinatura, que pode ser ampliada para diferentes áreas, dando controle granular sobre permissões e políticas. Os principais escopos de assinatura são:
- Todas as APIs
- Uma única API
- Um produto
Um aplicativo que chama uma API protegida deve incluir a chave na solicitação.
Você pode regenerar essas chaves de assinatura a qualquer momento. Por exemplo, regenere as chaves de subscrição se suspeitar que uma chave foi partilhada com utilizadores não autorizados.
Cada subscrição tem duas chaves: uma primária e uma secundária. Ter duas chaves facilita quando você precisa regenerar uma chave. Por exemplo, se quiser alterar a chave primária e evitar períodos de indisponibilidade, utilize a chave secundária nas suas aplicações.
No caso de produtos para os quais são ativadas subscrições, tem de fornecer uma chave ao efetuar chamadas para APIs nesses produtos. Enquanto programador, pode obter uma chave ao enviar um pedido de subscrição. Esse processo é uma parte essencial do fluxo de trabalho do Gerenciamento de API.
Nota
Criar novos usuários e dar-lhes suas chaves de assinatura para que eles possam acessar a API é uma parte essencial do fluxo de trabalho de Gerenciamento de API, mas está fora do escopo deste módulo.
Chamar uma API com a chave de subscrição
As aplicações têm de incluir uma chave válida em todos os pedidos HTTP ao efetuarem chamadas para pontos finais da API protegidos por uma subscrição. As chaves podem ser transmitidas no cabeçalho do pedido ou sob a forma de uma cadeia de consulta no URL.
O nome do cabeçalho predefinido é Ocp-Apim-Subscription-Key e a cadeia de consulta predefinida é subscription-key.
Para testar suas chamadas de API, você pode usar o portal do desenvolvedor (se estiver disponível na camada de serviço), uma ferramenta de linha de comando, como curl, ou outras ferramentas de cliente REST.
Aqui está um exemplo de uma solicitação GET que passa uma chave no cabeçalho da solicitação usando o comando curl :
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Eis um comando curl de exemplo que transmite uma chave no URL sob a forma de uma cadeia de consulta:
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
Se a chave não for passada no cabeçalho ou como uma cadeia de caracteres de consulta na URL, você obterá uma resposta 401 Acesso Negado do gateway de API.