Chamar uma API com uma chave de assinatura
Ao publicar uma API, geralmente, você deseja ter algum nível de controle sobre quem pode acessar a API por meio do gateway. As chaves de assinatura são uma maneira de restringir o acesso a uma API.
Aqui, você aprenderá a usar chaves de assinatura para proteger suas APIs.
Assinaturas e chaves
Para proteger suas APIs, você pode usar uma chave de assinatura.
Observação
Em ambientes de produção do Gerenciamento de API, normalmente, você combinará uma chave de assinatura com outros mecanismos para proteger as APIs contra o uso não autorizado, como autenticação de certificado ou autorização OAuth 2.0. Eles estão fora do escopo deste módulo.
Uma chave de assinatura é uma cadeia de caracteres exclusiva gerada automaticamente, transmitida nos cabeçalhos da solicitação do cliente ou como uma cadeia de consulta na URL. A chave está diretamente relacionada a uma assinatura, que pode ser direcionada para diferentes áreas, dando controle granular sobre permissões e políticas. Os escopos de assinatura principais são:
- Todas as APIs
- Uma única API
- Um produto
Um aplicativo que chama uma API protegida precisa incluir a chave na solicitação.
Você pode regenerar essas chaves de assinatura a qualquer momento. Por exemplo, regenere as chaves de assinatura se suspeitar que uma chave foi compartilhada com usuários não autorizados.
Toda assinatura tem duas chaves, uma primária e uma secundária. Ter duas chaves facilita a regeneração de uma chave. Por exemplo, se você quiser alterar a chave primária e evitar tempo de inatividade, use a chave secundária em seus aplicativos.
Para produtos em que assinaturas estão habilitadas, você precisa fornecer uma chave ao fazer chamadas para APIs no produto. Como desenvolvedor, você pode obter uma chave enviando uma solicitação de assinatura. Esse processo é uma parte essencial do fluxo de trabalho do Gerenciamento de API.
Observação
Criar usuários e dar a eles suas chaves de assinatura para que possam acessar a API é uma parte fundamental do fluxo de trabalho do Gerenciamento de API, mas está fora do escopo deste módulo.
Chamar uma API com a chave de assinatura
Os aplicativos precisam incluir uma chave válida em todas as solicitações HTTP ao fazer chamadas para pontos de extremidade de API protegidos por uma assinatura. As chaves podem ser passadas no cabeçalho da solicitação ou como uma cadeia de consulta na URL.
O nome de cabeçalho padrão é Ocp-Apim-Subscription-Key e a cadeia de consulta padrão é subscription-key.
Para testar suas chamadas de API, você pode usar o portal do desenvolvedor (se estiver disponível no seu nível 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
Veja um exemplo de comando curl que passa uma chave na URL como uma cadeia de consulta:
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
Se a chave não for transmitida no cabeçalho ou como uma cadeia de consulta na URL, você receberá uma resposta 401 Acesso Negado do gateway de API.