Criar assinaturas no Gerenciamento de API do Azure
Ao publicar uma API com o Gerenciamento de API, você define quem pode acessar a API por meio do gateway.
Para seu aplicativo meteorológico, você deseja garantir que somente os clientes que assinaram o serviço possam acessar a API e usar seus dados de previsão. Você obtém esse controle de acesso emitindo chaves de assinatura.
Importante
Nesse contexto, as assinaturas são diferentes das assinaturas do Azure usadas para gerenciar sua conta do Azure.
Aqui, você aprenderá a usar chaves de assinatura para proteger suas APIs.
Assinaturas e chaves
Você pode optar por disponibilizar suas APIs e as informações que elas contêm gratuitamente. Mas, em geral, é recomendável restringir o acesso aos usuários pagantes ou às organizações com as quais você tenha uma relação comercial. Uma forma de controlar o acesso às APIs é usando assinaturas. As assinaturas são usadas para segmentar o acesso de usuário a uma API.
As chaves de assinatura formam a autorização para permitir o acesso a essas assinaturas. Sempre que um cliente fizer uma solicitação a uma API protegida, ele precisará incluir uma chave de assinatura válida na solicitação HTTP ou a chamada será rejeitada.
Uma chave de assinatura é uma chave exclusiva gerada automaticamente que pode ser transmitida como parte de uma chamada à API. A chave está diretamente relacionada a uma assinatura, que pode ter um escopo definido para diferentes áreas. As assinaturas oferecem um controle granular sobre permissões e políticas.
Os três escopos de assinatura principais são:
| Escopo | Detalhes |
|---|---|
| Todas as APIs | Aplica-se a todas as APIs acessíveis por meio do gateway. |
| Única API | Aplica-se a uma única API importada e a todos os seus pontos de extremidade. |
| Produto | Um produto é uma coleção de uma ou mais APIs que você configura no Gerenciamento de API. Você pode atribuir APIs a mais de um produto. Os produtos podem ter diferentes regras de acesso, cotas de uso e termos de uso. Portanto, caso deseje que seus parceiros e seus fornecedores tenham direitos de acesso diferentes à API de WeatherData, atribua a API a um produto e, em seguida, use o portal do Azure para associar as APIs a um produto. |
Os aplicativos que chamam uma API protegida precisam incluir uma chave de assinatura em cada solicitação.
Você poderá regenerar essas chaves de assinatura a qualquer momento. Por exemplo, se suspeitar que uma chave foi compartilhada com usuários não autorizados, você poderá criar outra.
Toda assinatura tem duas chaves: uma primária e uma secundária. Ter duas chaves facilita regenerar uma chave. Por exemplo, caso deseje alterar a chave primária e evitar o tempo de inatividade, use a chave secundária em seus aplicativos.
Para os produtos em que as assinaturas estão habilitadas, os clientes precisarão fornecer uma chave ao fazer chamadas às APIs nesse produto. Os desenvolvedores podem obter uma chave enviando uma solicitação de assinatura. Se você aprovar a solicitação, precisará enviar a chave de assinatura com segurança, por exemplo, em uma mensagem criptografada. Essa etapa é uma parte importante do fluxo de trabalho do Gerenciamento de API.
Chamar uma API com a chave de assinatura
Os aplicativos precisam incluir uma chave válida em todas as solicitações HTTP que fazem chamadas para pontos de extremidade de API protegidos por uma assinatura. As chaves podem ser passadas no cabeçalho da solicitação ou como um parâmetro da cadeia de caracteres de consulta na URL.
O nome de cabeçalho da chave de assinatura padrão é Ocp-Apim-Subscription-Key, e o nome da cadeia de caracteres de consulta padrão é subscription-key.
Para testar as chamadas à API, use um console de teste no portal do Azure, o portal do desenvolvedor ou as ferramentas de linha de comando, como o cURL. Este é um exemplo de uma solicitação GET usando o portal do desenvolvedor, que mostra o cabeçalho da chave de assinatura:
Aqui está um exemplo de como você passaria uma chave em um cabeçalho de solicitação usando curl:
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Veja está um exemplo de como você usaria um comando do curl para passar uma chave como uma cadeia de caracteres de consulta em uma URL:
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
Se uma chave obrigatória não for transmitida no cabeçalho ou como uma cadeia de consulta na URL, você receberá a resposta 401 Acesso Negado do gateway de API.