Creazione e gestione delle chiavi API

Questa pagina spiega come creare e gestire le chiavi API utilizzando l'API delle chiavi API.

Per informazioni su come utilizzare una chiave API con le chiamate alle Google Cloud API, consulta Utilizzare le chiavi API.

Prima di iniziare

La pagina utilizza curl e Google Cloud CLI per inviare richieste all'API delle chiavi API. Per informazioni dettagliate sulla configurazione per sperimentare l'API, consulta Introduzione alle chiavi API.

Creazione di una chiave API

Puoi creare una chiave API utilizzando il CreateKey metodo. Il metodo richiede un Key parametro. Puoi specificare solo i campi displayName e restrictions dell'oggetto Key. CreateKey non è un metodo sincrono. Quando effettui una chiamata a CreateKey, avvii un'operazione a lunga esecuzione operation. L'esempio seguente effettua una chiamata CreateKey per creare una chiave API senza limitazioni:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys -X POST -d '{"displayName" : "Example API key"}'

Se l'operazione ha esito positivo, il metodo restituisce un'operazione a lunga esecuzione nella risposta. Come descritto in Eseguire il polling delle operazioni a lunga esecuzione, effettui ripetutamente chiamate operations.get con il valore del campo name. Quando la risposta di operations.get contiene "done": true, l'oggetto response contiene una Key, simile alla seguente:

{
  "name": "operations/akmf.p7-103621867718-06f94db2-7e91-4c58-b826-e6b80e4dc3eb",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key",
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

Nell'oggetto response:

  • Il campo name contiene un identificatore univoco per la chiave API. Utilizza il valore nel campo name negli altri metodi che richiedono un nome di chiave. Questo valore non viene visualizzato nella Google Cloud console, ma puoi chiamare il ListKeys metodo per ottenere il names per tutte le tue chiavi API. Il campo Key.name è sempre nel seguente formato: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • Il campo displayName esegue il mapping al campo Name nella Google Cloud console, quindi potresti voler fornire un displayName quando chiami CreateKey.
  • Il campo keyString contiene la stringa che invii alle API che richiedono una chiave API. Il keyString esegue il mapping al campo API key nella Google Cloud console. Puoi chiamare il GetKeyString metodo per ottenere il keyString di una chiave API.
  • Il campo etag contiene un checksum calcolato dal server in base al valore corrente della chiave. Passa il valore etag quando chiami i metodi UpdateKey e DeleteKey.

ID chiave specificato dall'utente

Puoi specificare un keyId come parametro di query per il metodo CreateKey. Se specificato, il valore diventa il componente finale di Key.name.

Ad esempio, considera la seguente chiamata a CreateKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1 -X POST -d '{"displayName" : "Example API key"}'

Per questo esempio, il campo Key.name ha il seguente valore: 

    "name": "projects/PROJECT_NUMBER/locations/global/keys/my-test-key1"

Aggiornamento del nome visualizzato

Per modificare il displayName di una chiave API o per aggiungere un displayName a una chiave API creata senza, chiama il metodo UpdateKey. Quando chiami UpdateKey, avvii un'operazione a lunga esecuzione che aggiorna la chiave.

L'esempio seguente illustra come chiamare UpdateKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName -X PATCH -d '{"displayName": "New display name", "etag" : "ETAG"}'

Quando la risposta di operations.get contiene "done": true, la response contiene un oggetto Key con il displayName aggiornato.

Eliminazione di una chiave API

Per eliminare una chiave API, utilizza il metodo DeleteKey. Quando chiami DeleteKey, avvii un'operazione a lunga esecuzione che contrassegna la chiave come DELETED.

L'esempio seguente illustra come chiamare DeleteKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?etag="ETAG" -X DELETE

Quando la risposta di operations.get contiene "done": true, la response è simile alla seguente:

{
  "name": "operations/akmf.cdabc4df-cbff-4420-8c7e-65dc832c945d",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key"
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "deleteTime": "2021-03-24T22:35:37.290544Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

Una chiave API contrassegnata come DELETED non può essere utilizzata, ma non viene rimossa completamente dal nostro sistema. Per elencare le chiavi API ancora esistenti ma contrassegnate come DELETED, imposta show_deleted su true per il metodo ListKeys:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?show_deleted=true

Dopo 30 giorni, la chiave API viene eliminata definitivamente.

Ripristino di una chiave API

Per ripristinare una chiave API prima che venga eliminata definitivamente, chiama il metodo UndeleteKey. Quando chiami UndeleteKey, avvii un'operazione a lunga esecuzione che contrassegna la chiave come ACTIVE.

L'esempio seguente illustra come chiamare UndeleteKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete -X POST

Passaggi successivi