Questa pagina è stata tradotta dall'API Cloud Translation.

Limitazione dell'accesso all'API con le chiavi API

OpenAPI | gRPC

Puoi utilizzare 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 all'API ai client che dispongono di una chiave API e mostra anche come creare una chiave API.

La Extensible Service Proxy (ESP) utilizza l'API Service Control per convalidare una chiave API e la sua associazione con un'API abilitata per un progetto. Se imposti un requisito della chiave API nella tua API, le richieste al metodo, alla classe o all'API protetti vengono rifiutate, a meno che non dispongano di una chiave generata nel tuo progetto o in altri progetti appartenenti a sviluppatori a cui hai concessi l'accesso per abilitare l'API. Il progetto in cui è stata creata la chiave API non viene registrato e non viene aggiunto al l'intestazione della richiesta. Tuttavia, puoi visualizzare il progetto Google Cloud associato a un client in Endpoint > Servizi, come descritto in Filtrare per un progetto consumer specifico.

Per informazioni su quale progetto Google Cloud deve essere creata una chiave API vedi Condivisione delle API protette dalla chiave API.

Limitazione dell'accesso a tutti i metodi dell'API

Per richiedere una chiave API per accedere a tutti i metodi di un'API:

Apri il file openapi.yaml del progetto in un editor di testo.
In securityDefinitions:, aggiungi i valori api_key: apiKey, key e query come mostrato nello snippet di codice campione:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Viene stabilito uno "schema di sicurezza" chiamato api_key, che puoi utilizzare per difendere l'API. Per altre opzioni di definizione di api_key, consulta le limitazioni relative alla definizione delle chiavi API.
A livello superiore del file (non rientrato o nidificato), aggiungi api_key: [] alla direttiva security. Potresti dover aggiungere l'istruzione security oppure potrebbero essere già presenti:
```
  security:
    - api_key: []
```
Questa istruzione applica lo schema di sicurezza api_key a tutti i metodi in del file. Non inserire nulla all'interno delle parentesi. La specifica OpenAPI richiede un elenco vuoto per gli schemi di sicurezza che non utilizzano OAuth.

Limitazione dell'accesso a metodi API specifici

Per richiedere una chiave API per un metodo specifico:

Apri il file openapi.yaml del progetto in un editor di testo.
A livello superiore del file (non rientrato o nidificato), aggiungi una direttiva di sicurezza vuota per applicarla all'intera API:
```
security: []
```
In securityDefinitions:, aggiungi i valori api_key: apiKey, key, query come mostrato nello snippet di codice di esempio:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Viene stabilito uno "schema di sicurezza" chiamato api_key, che puoi utilizzare per difendere l'API. Per altre opzioni di definizione di api_key, consulta le limitazioni per la definizione della chiave API.
Aggiungi api_key: [] all'istruzione security nella definizione del metodo:
```
...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security:
  - api_key: []
  produces:
  ...
```
Questa istruzione applica lo schema di sicurezza api_key al metodo. Azioni sconsigliate qualsiasi cosa all'interno delle parentesi. La specifica OpenAPI richiede un elenco vuoto di schemi di sicurezza che non utilizzano OAuth.

Rimozione della restrizione relativa alla chiave API per un metodo

Per disattivare la convalida delle chiavi API per un determinato metodo anche accesso API limitato per l'API:

Apri il file openapi.yaml del progetto in un editor di testo.

Aggiungi un'istruzione security vuota nella definizione del metodo:

...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security: []
  produces:
  ...

Chiamata a un'API mediante una chiave API

Se un metodo API o un'API richiede una chiave API, fornisci la chiave utilizzando una query parametro key, come mostrato nel seguente esempio di curl:

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

dove ENDPOINTS_HOST e ENDPOINTS_KEY sono variabili di ambiente contenenti rispettivamente il nome host e la chiave API.

Condivisione delle API protette dalla chiave API

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

Devi distinguere tra i chiamanti della tua API per poter utilizzare le funzionalità di Endpoints, come le quote?
Tutti i chiamanti della tua API hanno i propri progetti Google Cloud?
Devi impostare diverse limitazioni per le chiavi API?

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

Concedi l'autorizzazione per abilitare l'API

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

Ad esempio, supponiamo che il tuo team abbia creato un'API per l'utilizzo interno da parte di vari programmi client della tua azienda e che ogni programma client abbia il proprio progetto Google Cloud. Per distinguere 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 per abilitare l'API nel progetto Google Cloud a cui è associato il programma client associati.

Per consentire agli utenti di creare la propria chiave API:

Nel progetto Google Cloud in cui è configurata l'API, concedi a ciascun utente per abilitare le tue tramite Google Cloud.
Contatta gli utenti e informalo che possono abilitare l'API nel proprio Google Cloud progetto e creare una chiave API.

Creare un progetto Google Cloud separato per ogni chiamante

Quando devi distinguere tra gli utenti che chiamano la tua API e non tutti gli utenti hanno progetti Google Cloud, puoi creare un progetto Google Cloud e una chiave API separati per ogni utente. Prima di creare i progetti, valuta attentamente i nomi in modo da poter identificare facilmente il chiamante associato al progetto.

Ad esempio, supponiamo che tu abbia clienti esterni della tua API e non hai idea di come sono stati creati i programmi client che chiamano la tua API. Forse alcuni clienti utilizzano i servizi Google Cloud e hanno un progetto Google Cloud, e e forse altri no. Per distinguere i chiamanti, devi creare un progetto Google Cloud e una chiave API distinti per ogni chiamante.

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

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

Crea una chiave API per ogni chiamante

Quando non devi distinguere tra i chiamanti dell'API, ma vuoi per aggiungere limitazioni delle chiavi API, puoi creare una chiave API separata per ogni chiamante all'interno dello 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, crea una chiave API per ogni cliente con le limitazioni della chiave API di cui hai bisogno.
Fornisci la chiave API a ogni chiamante.

Crea una chiave API per tutti i chiamanti

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

Per creare una chiave API per tutti gli utenti che chiamano:

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

Best practice

Se ti affidi alle chiavi API per proteggere l'accesso all'API e ai dati utente, assicurati di impostare il flag --service_control_network_fail_open su close durante la configurazione Le opzioni di avvio di Extensible Service Proxy V2 (ESPv2). Il valore predefinito per l'indicatore è open.

ESPv2 chiama Service Control per verificare le chiavi API. Se si verificano errori di rete durante la connessione a Service Control e ESPv2 non è in grado di verificare la chiave API, ciò garantisce che tutte le potenziali richieste effettuate all'API con chiavi fraudolente vengano rifiutate.