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 Google Cloud APIs, consulta Usa claves de API.

Antes de comenzar

En la página, se usa curl y Google Cloud CLI para enviar solicitudes a la API de API Keys. Consulta Introducción a la API de API Keys para obtener detalles sobre cómo prepararte para 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 Key parámetro. 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 operation. 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 se completa correctamente, el método muestra una operación de larga duración en la respuesta. Como se describe en Sondear 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 una Key, similar a lo 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:

  • El campo name contiene un identificador único para la clave de API. Usas el valor en el campo name en los otros métodos que requieren un nombre de clave. Este valor no se muestra en la Google Cloud consola, 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 Google Cloud consola, por lo que es posible que desees proporcionar un displayName cuando llames a CreateKey.
  • El campo keyString contiene la cadena que envías a las APIs que requieren una clave de API. El keyString se asigna al campo API key en la Google Cloud consola. Puedes llamar al GetKeyString método 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 etag cuando llames a los métodos UpdateKey y DeleteKey.

ID de clave especificado por el usuario

Puedes especificar un keyId como un 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"}'

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

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

Actualiza 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 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, el response contiene un objeto Key con el displayName actualizado.

Borra 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 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, la response es similar a la 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, configura show_deleted como verdadera 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.

Restablece 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 muestra cómo llamar a UndeleteKey:

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

¿Qué sigue?