Creazione e gestione delle chiavi API

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

Per informazioni su come utilizzare una chiave API per le chiamate alle API di Google Cloud, consulta la pagina relativa all'utilizzo delle chiavi API.

Prima di iniziare

La pagina utilizza curl con lo strumento a riga di comando oauth2l per inviare richieste all'API Chiavi API. Consulta la Guida introduttiva alle chiavi API per i dettagli su come configurare gli esperimenti con l'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. Invece, quando effettui una chiamata a CreateKey, avvia un'operazione di lunga durata. L'esempio seguente emette una chiamata CreateKey per creare una chiave API senza restrizioni:

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 di lunga durata nella risposta. Come descritto in Polling su operazioni a lunga esecuzione, si ripetaoperations.get chiamate con il valore della chiamataname. Quando la risposta di operations.get contiene "done": true, l'oggetto response contiene un valore 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. Puoi utilizzare il valore nel campo name negli altri metodi che richiedono un nome di chiave. Questo valore non viene visualizzato in Google Cloud Console, ma puoi chiamare il metodo ListKeys per ottenere names per tutte le chiavi API. Il campo Key.name è sempre nel seguente formato: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • Il campo displayName è mappato al campo Name in Cloud Console, quindi potrebbe essere necessario fornire un displayName quando chiami CreateKey.
  • Il campo keyString contiene la stringa da inviare alle API che richiedono una chiave API. keyString è mappato al campo API key in Cloud Console. Puoi chiamare il metodo GetKeyString per ottenere l'API keyString per una chiave API.
  • Il campo etag contiene un checksum calcolato dal server in base al valore corrente della chiave. Quando trasmetti i metodi UpdateKey e DeleteKey, trasmetti il valore etag.

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 al numero 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"

Clonazione di una chiave API

Per creare una copia di una chiave API nello stesso progetto Cloud, utilizza il metodo CloneKey. Quando chiami CloneKey, avvii un'operazione a lunga esecuzione che crea una chiave con gli stessi displayName e restrictions della chiave originale, ma name e keyString.

Il seguente esempio mostra come chiamare CloneKey:

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

Quando la risposta di operations.get contiene "done": true, response contiene il nuovo oggetto Key.

La nuova chiave ha gli stessi displayName e restrictions della chiave originale, ma un nuovo elemento name e keyString.

Aggiornamento del nome visualizzato

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

Il seguente esempio mostra 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 l'elemento 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.

Il seguente esempio mostra 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 al 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=="
  }
}

Non è possibile utilizzare una chiave API contrassegnata come DELETED, ma non è completamente rimossa dal nostro sistema. Dopo 30 giorni, la chiave API viene eliminata definitivamente. Puoi aggiungere un filtro al metodo ListKeys per restituire le chiavi API contrassegnate come DELETED:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?filter=state:DELETED

Ripristino di una chiave API

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

Il seguente esempio mostra come chiamare UndeleteKey:

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

Passaggi successivi