Crear y administrar claves de API

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

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

Antes de comenzar

La página usa curl con la herramienta de línea de comandos oauth2l para enviar solicitudes a la API de claves de API. Consulta Comenzar a usar las claves de API para obtener detalles sobre cómo configurar 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. El CreateKey no es un método síncrono. En su lugar, 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 se realiza de forma correcta, el método muestra una operación de larga duración en la respuesta. Como se describe enCómo sondear las operaciones de larga duración, haces reiteradamenteoperations.get llamadas con el valor delname. 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:

  • El campo name contiene un identificador único para la clave de API. Debes usar el valor en el campo name en los otros métodos que requieren un nombre de clave. Este valor no se muestra en Google Cloud Console, pero puedes llamar al método ListKeys a fin de obtener el names para 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 Cloud Console, por lo que es posible que quieras proporcionar un displayName cuando llames a CreateKey.
  • El campo keyString contiene la string que envías a las API que requieren una clave de API. keyString se asigna al campo API key en Cloud Console. Puedes llamar al método GetKeyString a fin de obtener el keyString para una clave de API.
  • El campo etag contiene una suma de verificación calculada por 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 especificada por el usuario

Puedes especificar un keyId como un parámetro de consulta 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"

Clona una clave de API

Para crear una copia de una clave de API en el mismo proyecto de Cloud, usa el método CloneKey. Cuando llamas a CloneKey, se inicia una operación de larga duración que crea una clave con el mismo displayName y restrictions que la clave original, pero name y keyString.

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 objeto de Key nuevo.

La clave nueva tiene los mismos displayName y restrictions que la clave original, pero name y keyString nuevos.

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 una, llama al método UpdateKey. Cuando llamas a UpdateKey, se inicia 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.

Borra una clave de API

Para borrar una clave de API, usa el método DeleteKey. Cuando llamas a DeleteKey, se inicia 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, response es similar a lo 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=="
  }
}

Una clave de API que está marcada como DELETED no se puede usar, pero tampoco se quita por completo de nuestro sistema. Después de 30 días, la clave de API se borra de forma permanente. Puedes agregar un filtro al método ListKeys para mostrar las claves de API que están marcadas como DELETED:

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

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, se inicia 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?