Créer et gérer des clés API

Cette page explique comment créer et gérer des clés API à l'aide de l'API Keys.

Pour savoir comment utiliser une clé API avec vos appels aux API Google Cloud , consultez Utiliser des clés API.

Avant de commencer

La page utilise curl et la Google Cloud CLI pour envoyer des requêtes à l'API API Keys. Pour savoir comment configurer l'API et l'expérimenter, consultez Premiers pas avec l'API API Keys.

Créer une clé API

Vous pouvez créer une clé API à l'aide de la méthode CreateKey. La méthode nécessite un paramètre Key. Vous ne pouvez spécifier que les champs displayName et restrictions de l'objet Key. CreateKey n'est pas une méthode synchrone. En revanche, lorsque vous émettez un appel à CreateKey, vous lancez une opération de longue durée. L'exemple suivant émet un appel CreateKey pour créer une clé API sans restriction :

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

En cas de réussite, la méthode renvoie une opération de longue durée dans la réponse. Comme décrit dans Interroger des opérations de longue durée, vous effectuez des appels operations.get à plusieurs reprises avec la valeur du champ name. Lorsque la réponse de operations.get contient "done": true, l'objet response contient un Key, semblable à ce qui suit :

{
  "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=="
  }
}

Dans l'objet response :

  • Le champ name contient un identifiant unique pour la clé API. Vous utilisez la valeur du champ name dans les autres méthodes qui nécessitent un nom de clé. Cette valeur ne s'affiche pas dans la console Google Cloud , mais vous pouvez appeler la méthode ListKeys pour obtenir le names de toutes vos clés API. Le champ Key.name est toujours au format suivant : projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • Le champ displayName correspond au champ Name dans la consoleGoogle Cloud . Vous pouvez donc fournir un displayName lorsque vous appelez CreateKey.
  • Le champ keyString contient la chaîne que vous envoyez aux API qui nécessitent une clé API. keyString correspond au champ API key dans la consoleGoogle Cloud . Vous pouvez appeler la méthode GetKeyString pour obtenir le keyString d'une clé API.
  • Le champ etag contient une somme de contrôle calculée par le serveur en fonction de la valeur actuelle de la clé. Veuillez transmettre la valeur etag lorsque vous appelez les méthodes UpdateKey et DeleteKey.

ID de clé spécifié par l'utilisateur

Vous pouvez spécifier un keyId en tant que paramètre de requête pour la méthode CreateKey. Lorsqu'elle est spécifiée, la valeur devient le composant final de Key.name.

Par exemple, prenons l'appel suivant à CreateKey :

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

Dans cet exemple, le champ Key.name a la valeur suivante : 

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

Modifier le nom à afficher

Pour modifier le displayName d'une clé API ou ajouter un displayName à une clé API qui a été créée sans, appelez la méthode UpdateKey. Lorsque vous appelez UpdateKey, vous lancez une opération de longue durée qui met à jour la clé.

L'exemple suivant montre comment appeler 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"}'

Lorsque la réponse de operations.get contient "done": true, response contient un objet Key avec le displayName mis à jour.

Supprimer une clé API

Pour supprimer une clé API, utilisez la méthode DeleteKey. Lorsque vous appelez DeleteKey, vous lancez une opération de longue durée qui marque la clé comme DELETED.

L'exemple suivant montre comment appeler DeleteKey :

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

Lorsque la réponse de operations.get contient "done": true, response est semblable à ce qui suit :

{
  "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=="
  }
}

Une clé API marquée comme DELETED ne peut pas être utilisée, mais elle n'est pas non plus complètement supprimée de notre système. Pour lister les clés API qui existent toujours, mais qui sont marquées comme DELETED, définissez show_deleted sur "true" pour la méthode ListKeys :

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

Passé ce délai, la clé API est définitivement supprimée.

Restaurer une clé API

Pour restaurer une clé API avant qu'elle ne soit définitivement supprimée, appelez la méthode UndeleteKey. Lorsque vous appelez UndeleteKey, vous lancez une opération de longue durée qui marque la clé comme ACTIVE.

L'exemple suivant montre comment appeler UndeleteKey :

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

Étapes suivantes