Creazione e gestione delle chiavi API

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

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

Prima di iniziare

La pagina utilizza curl e Google Cloud CLI per inviare richieste all'API API Keys. Per informazioni dettagliate su come configurare l'API per sperimentarla, consulta la sezione Introduzione alle chiavi API.

Creazione di una chiave API

Puoi creare una chiave API utilizzando il metodo CreateKey. Il metodo richiede un parametro Key. 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. Il seguente esempio emette 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"}'

In caso di esito positivo, il metodo restituisce un'operazione a lunga esecuzione nella risposta. Come descritto in Polling su 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 un Key, simile al 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. Utilizzi il valore nel campo name negli altri metodi che richiedono un nome chiave. Questo valore non viene visualizzato nella console Google Cloud , ma puoi chiamare il metodo ListKeys 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 viene mappato al campo Name nella consoleGoogle Cloud , quindi ti consigliamo di fornire un displayName quando chiami CreateKey.
  • Il campo keyString contiene la stringa che invii alle API che richiedono una chiave API. keyString corrisponde al campo API key nella consoleGoogle Cloud . Puoi chiamare il metodo GetKeyString per ottenere il keyString per una chiave API.
  • Il campo etag contiene un checksum calcolato dal server in base al valore attuale della chiave. Trasmetti 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, response contiene un oggetto Key con 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, 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