Crear y administrar claves de API

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

Para obtener información sobre cómo usar una clave de API con tus llamadas a las APIs de Google Cloud , consulta Cómo usar claves de API.

Antes de comenzar

En la página, se usan curl y Google Cloud CLI para enviar solicitudes a la API de API Keys. Consulta Introducción a la API de claves de API para obtener detalles sobre cómo configurar tu entorno y experimentar con la API.

Crea una clave de API

Puedes crear una clave de API con el método CreateKey. El método requiere un parámetro Key. Solo puedes especificar los campos displayName y restrictions del objeto Key. CreateKey no es un método síncrono. En cambio, cuando emites una llamada a CreateKey, inicias una operación de larga duración. En el siguiente ejemplo, se emite una llamada a 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 la operación se realiza correctamente, el método devuelve una operación de larga duración en la respuesta. Como se describe en Sondea operaciones de larga duración, realizas llamadas operations.get de forma repetida con el valor del campo name. Cuando la respuesta de operations.get contiene "done": true, el objeto response contiene un Key, similar al siguiente:

{
  "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, se incluye lo siguiente:

  • El campo name contiene un identificador único para la clave de API. Usas el valor del campo name en los otros métodos que requieren 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 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 deGoogle Cloud , por lo que te recomendamos que proporciones un displayName cuando llames a CreateKey.
  • El campo keyString contiene la cadena que envías a las APIs que requieren una clave de API. keyString se asigna al campo API key en la consola deGoogle 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 que calcula el servidor según el valor actual de la clave. Pasa el valor de etag cuando llames a los métodos UpdateKey y DeleteKey.

ID de clave especificado por el usuario

Puedes especificar un keyId como parámetro de búsqueda para el método CreateKey. Cuando se especifica, el valor se convierte en el componente final de Key.name.

Por ejemplo, considera 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"

Cómo actualizar el nombre visible

Para cambiar el displayName de una clave de API o agregar un displayName a una clave de API que se creó sin uno, 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 ilustra 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 incluye un objeto Key con el displayName actualizado.

Cómo borrar una clave de API

Para borrar una clave de API, usa 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 ilustra 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 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=="
  }
}

No se puede usar una clave de API marcada como DELETED, pero tampoco se quita por completo de nuestro sistema. Para enumerar las claves de API que aún existen, pero que están marcadas como DELETED, establece show_deleted como verdadero para el método ListKeys:

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

Después de 30 días, la clave de API se borra de forma permanente.

Cómo restablecer una clave de API

Para restablecer una clave de API antes de que se borre 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 ilustra cómo llamar a UndeleteKey:

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

¿Qué sigue?