Questa pagina è stata tradotta dall'API Cloud Translation.

Limitazione dell'accesso alle API con le chiavi API

OpenAPI | gRPC

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 dispongono di una chiave API e mostra anche come creare una chiave API.

Extensible Service Proxy (ESP) utilizza l'API Service Control per convalidare una chiave API e la sua associazione all'API abilitata di un progetto. Se imposti un requisito per la chiave API nella tua API, le richieste al metodo, alla classe o all'API protetti vengono rifiutate a meno che non abbiano una chiave generata nel tuo progetto o in altri progetti appartenenti a sviluppatori a cui hai concesso l'accesso per abilitare la tua 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 Clouda cui è associato un client in Endpoint > Servizi, come descritto in Filtrare in base a un progetto consumer specifico.

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

Limitazione dell'accesso a tutti i metodi 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, 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"
```
In questo modo viene stabilito uno "schema di sicurezza" chiamato api_key, che puoi utilizzare per proteggere l'API. Per altre opzioni di definizione di api_key, consulta Limitazioni della definizione della chiave API.
Al livello superiore del file (non rientrato o nidificato), aggiungi api_key: [] alla direttiva security . Potresti dover aggiungere la direttiva security o potrebbe essere già presente:
```
  security:
    - api_key: []
```
Questa direttiva applica lo schema di sicurezza api_key a tutti i metodi 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.

Limitare l'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.
Al livello superiore del file (senza rientro o nidificazione), aggiungi una direttiva security vuota per applicarla all'intera API:
```
security: []
```
In securityDefinitions:, aggiungi i valori api_key: apiKey, key, 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"
```
In questo modo viene stabilito uno "schema di sicurezza" chiamato api_key, che puoi utilizzare per proteggere l'API. Per altre opzioni di definizione di api_key, consulta Limitazioni della 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 direttiva applica lo schema di sicurezza api_key al metodo. Non inserire nulla all'interno delle parentesi. La specifica OpenAPI richiede un elenco vuoto per gli schemi di sicurezza che non utilizzano OAuth.

Rimozione della limitazione della chiave API per un metodo

Per disattivare la convalida della chiave API per un metodo specifico anche se hai limitato l'accesso all'API:

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

Aggiungi una direttiva security vuota nella definizione del metodo:

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

Chiamare un'API utilizzando una chiave API

Se un'API o un metodo API richiede una chiave API, fornisci la chiave utilizzando un parametro di query denominato 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 di API protette da 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 la tua API, il progetto in cui viene creata la chiave API dipende dalle risposte alle seguenti domande: Google Cloud

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

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

Concedi l'autorizzazione per abilitare l'API

Quando devi distinguere tra i chiamanti della tua API e ogni chiamante ha il proprio progetto Google Cloud , puoi concedere ai principal l'autorizzazione per abilitare l'API nel 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'uso interno da parte di vari programmi client nella tua azienda e che ogni programma client abbia il proprio Google Cloud progetto. 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.

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 abilitare l'API.
Contatta gli utenti e comunica loro che possono abilitare la tua API nel loro progetto Google Cloude creare una chiave API.

Crea un progetto Google Cloud separato per ogni chiamante

Quando devi distinguere tra i chiamanti della tua API e non tutti i chiamanti hanno progetti, puoi creare un progetto e una chiave API separati per ogni chiamante. Google Cloud Google Cloud 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 che tu non abbia idea di come siano stati creati i programmi client che chiamano la tua API. Forse alcuni clienti utilizzano i servizi Google Cloud e hanno un progetto Google Cloud , mentre altri no. Per distinguere i chiamanti, devi creare un progetto Google Cloud e una chiave API separati per ciascun chiamante.

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

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

Crea una chiave API per ogni chiamante

Quando non devi distinguere tra i chiamanti della tua 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 l'API è abilitata, crea una chiave API per ogni cliente che dispone delle 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 è necessario distinguere tra i chiamanti dell'API e non è necessario aggiungere limitazioni API, ma vuoi comunque richiedere una chiave API (per impedire l'accesso anonimo, ad esempio), puoi creare una chiave API da utilizzare per 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 l'API è abilitata, crea una chiave API per tutti i chiamanti con le limitazioni della chiave API necessarie.
Fornisci la stessa chiave API a ogni chiamante.

Best practice

Se utilizzi le chiavi API per proteggere l'accesso alla tua API e ai dati utente, assicurati di impostare il flag --service_control_network_fail_policy su close durante la configurazione delle opzioni di avvio di Extensible Service Proxy V2 (ESPv2). Il valore predefinito del flag è 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 riesce a verificare la chiave API, le potenziali richieste effettuate alla tua API con chiavi fraudolente vengono rifiutate.

Limitazione dell'accesso alle API con le chiavi API Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.