Crear y gestionar claves de API

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

En esta página se explica cómo crear y gestionar claves de API con la API de claves de API.

Para obtener información sobre el uso de una clave de API con las llamadas a las API de Google Cloud, consulta la página sobre el uso de claves de API.

Antes de empezar

La página utiliza curl con la herramienta de línea de comandos oauth2l para enviar solicitudes a la API de las claves de API. Consulta la página Primeros pasos con las claves de API para obtener información detallada sobre cómo configurar este tipo de experimentos.

Creando una clave de API

Puedes crear una clave de API mediante el método CreateKey. El método requiere un parámetro Key. Solo se pueden especificar los campos displayName y restrictions del objeto Key. CreateKey no es un método síncrono. Por el contrario, cuando envías una llamada a CreateKey, inicias una operación de larga duración. En el siguiente ejemplo se emite una llamada CreateKey para crear una clave de API sin restricciones:

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

Si funciona correctamente, el método devuelve una operación de larga duración en la respuesta. Tal como se describe en Sondear operaciones de larga duración , repitesoperations.get con el valor de la etiquetaname (por ejemplo, example.com). Cuando la respuesta de operations.get contiene "done": true, el objeto response contiene un elemento Key similar a este:

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

En el objeto response:

  • El campo name contiene un identificador único para la clave de API. Puedes usar el valor del campo name en otros métodos que requieran un nombre de clave. Este valor no se muestra en la consola de Google Cloud, pero puedes llamar al método ListKeys para obtener el valor names de todas tus claves de API. El campo Key.name siempre tiene el siguiente formato: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • El campo displayName se asigna al campo Name en la consola de Cloud, por lo que te recomendamos que proporciones displayName al llamar a CreateKey.
  • El campo keyString contiene la cadena que envías a las API que requieren una clave de API. El valor de keyString se asigna al campo API key en la consola de Cloud. Puedes llamar al método GetKeyString para obtener el keyString de una clave de API.
  • El campo etag contiene una suma de comprobación calculada por el servidor según el valor actual de la clave. Transmite el valor etag al llamar a los métodos UpdateKey y DeleteKey.

ID de clave especificado por el usuario

Puedes especificar keyId como parámetro de consulta del método CreateKey. Si se especifica, el valor se convierte en el componente final de Key.name.

Por ejemplo, imagina la siguiente llamada 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"}'

En este ejemplo, el campo Key.name tiene el siguiente valor: 

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

Clonar una clave de API

Para hacer una copia de una clave de API en el mismo proyecto de Cloud, utiliza el método CloneKey. Cuando llamesCloneKey, se inicia una operación de larga duración que crea una clave con el mismodisplayName yrestrictions como la clave original, peroname ykeyString.

En el siguiente ejemplo se muestra cómo llamar a CloneKey:

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

Cuando la respuesta de operations.get contiene "done": true, response contiene el nuevo objeto Key.

La nueva clave tiene los mismos displayName y restrictions que la clave original, pero es un elemento name y keyString nuevo.

Actualizando el nombre visible

Para cambiar la displayName de una clave de API o para añadir una displayName a una clave de API que se haya creado sin una, llama al método UpdateKey. Cuando llamas a UpdateKey, inicias una operación de larga duración que actualiza la clave.

En el siguiente ejemplo se muestra cómo llamar a 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"}'

Cuando la respuesta de operations.get contiene "done": true, response contiene un objeto Key con el displayName actualizado.

Eliminar una clave de API

Para eliminar una clave de API, utiliza el método DeleteKey. Cuando llamas a DeleteKey, inicias una operación de larga duración que marca la clave como DELETED.

En el siguiente ejemplo se muestra cómo llamar a DeleteKey:

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

Cuando la respuesta de operations.get contiene "done": true, el valor de response es similar al siguiente:

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

Las claves de API marcadas como DELETED no se pueden usar, pero tampoco se eliminan completamente de nuestro sistema. Al cabo de 30 días, la clave de API se elimina de forma permanente. Puedes añadir un filtro al método ListKeys para devolver claves de API marcadas como DELETED:

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

Restaurar una clave de API

Para restaurar una clave de API antes de que se elimine de forma permanente, llama al método UndeleteKey. Cuando llamas a UndeleteKey, inicias una operación de larga duración que marca la clave como ACTIVE.

En el siguiente ejemplo se muestra cómo llamar a UndeleteKey:

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

Siguientes pasos