Limitazione dell'accesso all'API con le chiavi API

Puoi utilizzare le chiavi API per limitare l'accesso a metodi API specifici o a tutti i metodi di un'API. Questa pagina descrive come limitare l'accesso API ai client che hanno una chiave API e mostra anche come creare una chiave API.

Se imposti un requisito della chiave API nell'API, le richieste al metodo, alla classe o all'API protetti vengono rifiutate, a meno che non abbiano una chiave generata nel progetto o all'interno di altri progetti appartenenti a sviluppatori con cui hai concesso l'accesso per abilitare l'API. Il progetto in cui è stata creata la chiave API non viene registrato e non viene aggiunto all'intestazione della richiesta. Tuttavia, puoi visualizzare il progetto Google Cloud a cui è associato un client nella pagina Servizi endpoint, come descritto in Filtrare per progetto consumer specifico.

Per informazioni sul progetto Google Cloud in cui deve essere creata una chiave API, consulta API di condivisione protette da chiave API.

Limitazione dell'accesso a tutti i metodi dell'API

Per richiedere una chiave API per tutte le chiamate nell'API, aggiungi apiKeyRequired = AnnotationBoolean.TRUE all'annotazione@Api. Ad esempio:

@Api(
  name = "echo",
  version = "v1",
  apiKeyRequired = AnnotationBoolean.TRUE
  )
public class Echo {
//API class and methods...
}

Limitazione dell'accesso a metodi API specifici

Per richiedere una chiave API per tutte le chiamate in un metodo API specifico, aggiungi apiKeyRequired = AnnotationBoolean.TRUE all'annotazione@ApiMethod. Ad esempio:

@ApiMethod(name = "echo_api_key", path = "echo_api_key", apiKeyRequired = AnnotationBoolean.TRUE)
public Message echoApiKey(Message message, @Named("n") @Nullable Integer n) {
  return doEcho(message, n);
}

Per richiedere una chiave API per tutte le chiamate in una classe API specifica, aggiungi apiKeyRequired = AnnotationBoolean.TRUE all'annotazione @ApiClass.

Rimozione della limitazione della chiave API per un metodo

Per disattivare la convalida delle chiavi API per un metodo API o API, rimuovi api_key_required=True (Python) o apiKeyRequired = AnnotationBoolean.TRUE (Java) dall'annotazione o dal decorator dell'API o del metodo. Poi ricompila ed esegui nuovamente il deployment.

Chiamare un'API mediante una chiave API

Se un metodo API o API richiede una chiave API, fornisci la chiave utilizzando un parametro di query denominato key, come mostrato in questo esempio di cURL:

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"message": "echo"}' \
    "${HOST}/_ah/api/echo/v1/echo_api_key?key=${API_KEY}"

dove HOST e API_KEY sono variabili contenenti rispettivamente il nome host dell'API e la chiave API. Sostituisci echo con il nome dell'API e v1 con la versione dell'API.

Condivisione di API protette dalla chiave API

Le chiavi API sono associate al progetto Google Cloud in cui sono state create. Se hai deciso di richiedere una chiave API per l'API, il progetto Google Cloud in cui viene creata la chiave API dipende dalle risposte alle seguenti domande:

Devi distinguere tra i chiamanti dell'API in modo da poter utilizzare le funzionalità di Endpoints come le quotas?
Tutti i chiamanti della tua API hanno progetti Google Cloud propri?
Devi impostare limitazioni relative alle chiavi API diverse?

Puoi utilizzare il seguente albero decisionale come guida per decidere in quale progetto Google Cloud creare la chiave API.

Concedi l'autorizzazione per abilitare l'API

Se devi distinguere tra i chiamanti della tua API e ogni chiamante ha un proprio progetto Google Cloud, puoi concedere alle entità l'autorizzazione per abilitare l'API nel proprio progetto Google Cloud. In questo modo, gli utenti dell'API possono creare la propria chiave API da utilizzare con l'API.

Ad esempio, supponiamo che il tuo team abbia creato un'API per uso interno da parte di vari programmi client della tua azienda e che ogni programma client abbia un proprio progetto Google Cloud. Per distinguere tra i chiamanti della tua API, la chiave API per ogni chiamante deve essere creata in un progetto Google Cloud diverso. Puoi concedere ai tuoi colleghi l'autorizzazione ad attivare l'API nel progetto Google Cloud a cui è associato il programma client.

Per consentire agli utenti di creare la propria chiave API:

Nel progetto Google Cloud in cui è configurata l'API, concedi a ogni utente l'autorizzazione per attivare l'API.
Contatta gli utenti e chiedi loro che possono abilitare l'API nel loro progetto Google Cloud e creare una chiave API.

Creare un progetto Google Cloud separato per ogni chiamante

Se devi distinguere tra i chiamanti della tua API e non tutti i chiamanti hanno progetti Google Cloud, puoi creare un progetto Google Cloud e una chiave API separati per ogni chiamante. Prima di creare i progetti, valutane i nomi in modo da poter identificare facilmente il chiamante associato al progetto.

Ad esempio, supponi di avere clienti esterni della tua API e di non avere idea di come sono stati creati i programmi client che chiamano l'API. Forse alcuni clienti utilizzano i servizi Google Cloud e hanno un progetto Google Cloud; altri forse non lo usano. Per distinguere i chiamanti, devi creare un progetto Google Cloud e una chiave API separati per ogni chiamante.

Per creare un progetto Google Cloud e una chiave API separati per ogni chiamante:

Creare un progetto separato per ogni chiamante.
In ogni progetto, abilita l'API e crea una chiave API.
Assegna la chiave API a ogni chiamante.

Creare una chiave API per ogni chiamante

Se non hai bisogno di distinguere tra i chiamanti dell'API, ma vuoi aggiungere limitazioni relative alle chiavi API, puoi creare una chiave API separata per ogni chiamante nello stesso progetto.

Per creare una chiave API per ogni chiamante nello stesso progetto:

Nel progetto in cui è configurata l'API o in un progetto in cui è abilitata l'API, crea una chiave API per ogni cliente con le restrizioni relative alle chiavi API di cui hai bisogno.
Assegna la chiave API a ogni chiamante.

Creare una chiave API per tutti i chiamanti

Quando non devi distinguere tra i chiamanti della tua API e non devi aggiungere limitazioni delle API, ma vuoi comunque richiedere una chiave API (ad esempio per impedire l'accesso anonimo), puoi creare una chiave API utilizzabile da tutti i chiamanti.

Per creare una chiave API per tutti i chiamanti:

Nel progetto in cui è configurata l'API o in un progetto in cui è abilitata l'API, crea una chiave API per tutti i chiamanti.
Assegna la stessa chiave API a ogni chiamante.

Passaggi successivi

Protezione di una chiave API