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

Preview

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent bénéficier d'une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

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

Pour plus d'informations sur l'utilisation d'une clé API avec vos appels aux API Google Cloud, consultez la section Utiliser des clés API.

Avant de commencer

La page utilisecurl avec la oauth2l pour envoyer des requêtes à l'API Keys API. Pour savoir comment configurer l'API, consultez la page Premiers pas avec les clés API.

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. L'élément CreateKey n'est pas une méthode synchrone. Lorsque vous envoyez 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 la section Interroger des opérations de longue durée, vous effectuez régulièrement des appels operations.get avec la valeur de name }. Lorsque la réponse de operations.get contient "done": true, l'objet response contient un objet Key, semblable à celui-ci:

{
  "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 pouvez utiliser la valeur du champ name dans les autres méthodes nécessitant un nom de clé. Cette valeur n'est pas affichée dans Google Cloud Console, mais vous pouvez appeler la méthode ListKeys pour obtenir le paramètre names pour 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 Cloud Console. Vous devrez donc peut-être fournir une valeur displayName lorsque vous appelez CreateKey.
• Le champ keyString contient la chaîne que vous envoyez aux API nécessitant une clé API. Le champ keyString correspond au champ API key dans Cloud Console. Vous pouvez appeler la méthode GetKeyString pour obtenir l'objet keyString correspondant à 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 comme paramètre de requête pour la méthode CreateKey. Si spécifié, la valeur devient le composant final de Key.name.

Prenons l'exemple suivant pour appeler CreateKey:

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

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

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

Cloner une clé API

Pour créer une copie d'une clé API dans le même projet Cloud, utilisez la méthode CloneKey. Lorsque vous appelez CloneKey, vous lancez une opération de longue durée qui crée une clé avec les mêmes displayName et restrictions que la clé d'origine, mais des valeurs name et keyString.

L'exemple suivant montre comment appeler CloneKey:

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

Lorsque la réponse de operations.get contient "done": true, response contient le nouvel objet Key.

La nouvelle clé possède les mêmes valeurs displayName et restrictions que la clé d'origine, mais les nouvelles name et keyString.

Remarque :Nous vous recommandons de alterner régulièrement vos clés API. Une fois que vous avez mis à jour votre application pour qu'elle utilise les nouvelles clés, vous pouvez supprimer les anciennes. Pour en savoir plus, consultez la page Sécuriser une clé API.

Mettre à jour le nom à afficher

Pour modifier le paramètre displayName d'une clé API ou ajouter displayName à une clé API créée sans clé, 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, l'objet response contient un objet Key avec l'objet 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, la valeur response est semblable à la suivante:

{
  "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 complètement supprimée de notre système. Après 30 jours, la clé API est définitivement supprimée. Vous pouvez ajouter un filtre à la méthode ListKeys pour renvoyer des clés API marquées comme DELETED:

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

Restaurer une clé API

Pour restaurer une clé API avant sa suppression définitive, 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

Étape suivante

• Obtenir des informations sur les clés API
• Ajouter des restrictions aux clés API
• Afficher les journaux d'audit Cloud
• Dépannage