Chiamare un'API con una chiave di sottoscrizione

  • 5 minuti

Quando si pubblica un'API, spesso si vuole avere un controllo di un certo livello su chi può accedere all'API tramite il gateway. Le chiavi di sottoscrizione sono un modo per limitare l'accesso a un'API.

Qui si apprenderà come usare le chiavi di sottoscrizione per proteggere le API.

Sottoscrizioni e chiavi

Per proteggere le API, è possibile usare una chiave di sottoscrizione.

Nota

Negli ambienti di produzione Gestione API, in genere si combina una chiave di sottoscrizione con altri meccanismi per proteggere le API da usi non autorizzati, ad esempio l'autenticazione del certificato o l'autorizzazione OAuth 2.0. questi meccanismi non rientrano nell'ambito di questo modulo.

Una chiave di sottoscrizione è una stringa generata automaticamente univoca, che viene passata nelle intestazioni della richiesta client o come stringa di query nell'URL. La chiave è direttamente correlata a una sottoscrizione che può essere inclusa nell'ambito di diverse aree, offrendo un controllo granulare su autorizzazioni e criteri. Gli ambiti principali di una sottoscrizione sono:

  • Tutte le API
  • Una singola API
  • Prodotto

Un'applicazione che chiama un'API protetta deve includere la chiave nella richiesta.

È possibile rigenerare le chiavi di sottoscrizione in qualsiasi momento. È possibile rigenerare le chiavi di sottoscrizione se ad esempio si sospetta che una chiave sia stata condivisa con utenti non autorizzati.

Subscription keys.

Ogni sottoscrizione ha due chiavi, una primaria e una secondaria. La presenza di due chiavi semplifica la rigenerazione di una chiave. Se ad esempio si vuole cambiare la chiave primaria senza tempi di inattività, usare la chiave secondaria nelle app.

Per i prodotti in cui sono abilitate le sottoscrizioni, è necessario specificare una chiave quando si effettuano chiamate alle API in tale prodotto. Gli sviluppatori possono ottenere una chiave inviando una richiesta di sottoscrizione. Questo processo è una parte fondamentale del flusso di lavoro di Gestione API.

Nota

La creazione di nuovi utenti e l'assegnazione delle chiavi di sottoscrizione per consentire loro di accedere all'API sono una parte fondamentale del flusso di lavoro di Gestione API, ma non rientrano nell'ambito di questo modulo.

Chiamare un'API con la chiave di sottoscrizione

Le applicazioni devono includere una chiave valida in tutte le richieste HTTP quando effettuano chiamate agli endpoint dell'API protetti da una sottoscrizione. Le chiavi possono essere passate nell'intestazione della richiesta oppure come stringa di query nell'URL.

Il nome di intestazione predefinito è Ocp-Apim-Subscription-Key e la stringa di query predefinita è subscription-key.

Per testare le chiamate API, è possibile usare il portale per sviluppatori (se disponibile nel livello di servizio), uno strumento da riga di comando, ad esempio curl o altri strumenti come Postman.

Ecco un esempio di una richiesta GET che passa una chiave nell'intestazione della richiesta usando il comando curl:

curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path

Ecco un esempio di comando curl che passa una chiave nell'URL come stringa di query:

curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>

Se la chiave non viene passata nell'intestazione o come stringa di query nell'URL, si ottiene una risposta di accesso negato 401 dal gateway API.