Activadores de Cloud Storage

En Cloud Functions, un activador de Cloud Storage permite que se llame a una función en respuesta a los cambios en Cloud Storage. Cuando especificas un activador de Cloud Storage para una función, eliges un tipo de evento y un bucket de Cloud Storage. Se llamará a tu función cada vez que se produzca un cambio en un objeto (archivo) dentro del bucket especificado.

Se admiten los siguientes tipos de eventos de Cloud Storage:

Evento	Tipo de evento	Descripción
Objeto finalizado	2nd gen: `google.cloud.storage.object.v1.finalized` (a través de Eventarc) 1st gen: `google.storage.object.finalize`	Ocurre cuando se crea un objeto nuevo o se reemplaza un objeto existente y se crea una generación nueva de ese objeto.
Eliminación de un objeto	2nd gen: `google.cloud.storage.object.v1.deleted` (a través de Eventarc) 1st gen: `google.storage.object.delete`	Ocurre cuando un objeto se borra permanentemente.
Objeto archivado	2nd gen: `google.cloud.storage.object.v1.archived` (a través de Eventarc) 1st gen: `google.storage.object.archive`	Ocurre cuando una versión publicada de un objeto se convierte en una versión no actual. Consulta Control de versiones de objetos para obtener más información.
Actualización de los metadatos de un objeto	2nd gen: `google.cloud.storage.object.v1.metadataUpdated` (a través de Eventarc) 1st gen: `google.storage.object.metadataUpdate`	Ocurre cuando cambian los metadatos de un objeto existente.

Para que una función use un activador de Cloud Storage, debe implementarse como una función controlada por eventos:

Si usas una función de CloudEvent, los datos de eventos de Cloud Storage se pasan a tu función en el formato de CloudEvents y la carga útil de datos de CloudEvent es del tipo StorageObjectData.
Si usas una función en segundo plano, la carga útil de datos de eventos de Cloud Storage se pasa directamente a tu función en el formato StorageObjectData.

El repositorio de Eventos de Google contiene recursos adicionales para trabajar con datos de eventos.

Permisos

Para usar los activadores de Cloud Storage, el agente de servicio de Cloud Storage debe tener el rol de IAM Pub/Sub Publisher (roles/pubsub.publisher) en tu proyecto.

Deployment

Puedes especificar un activador de Cloud Storage cuando implementes una función. Consulta Implementa una Cloud Function a fin de obtener instrucciones generales para implementar una función, y consulta la siguiente información adicional específica sobre la configuración de activadores de Cloud Storage durante la implementación.

gcloud

Si implementas con la CLI de gcloud, puedes usar el tipo de evento Objeto finalizado de Cloud Storage con las siguientes marcas:

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-bucket=YOUR_STORAGE_BUCKET \
[--retry] \
...

La marca --trigger-bucket especifica el bucket de Cloud Storage que supervisará el activador. Los eventos Objeto finalizado dentro de este bucket activarán llamadas a tu función.
La marca --retry controla si se reintentan las llamadas a funciones con errores. Consulta Reintenta las funciones controladas por eventos para obtener más información.

Para usar tipos de eventos que no sean Objeto finalizado, usa las siguientes marcas:

Para Cloud Functions (2nd gen):

gcloud functions deploy YOUR_FUNCTION_NAME \
--gen2 \
--trigger-event-filters="type=EVENT_TYPE" \
--trigger-event-filters="bucket=YOUR_STORAGE_BUCKET" \
...

Para Cloud Functions (1st gen):

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-event=EVENT_TYPE \
--trigger-resource=YOUR_STORAGE_BUCKET \
...

Eventos heredados de Cloud Storage

Las funciones heredadas en Cloud Functions (1st gen) usan notificaciones de cambio de objeto heredadas para los activadores de Cloud Storage:

gcloud functions deploy YOUR_FUNCTION_NAME \
--trigger-event=providers/cloud.storage/eventTypes/object.change \
--trigger-resource=YOUR_STORAGE_BUCKET \
...

Este tipo de evento es compatible con funciones heredadas que ya consumen estos eventos. Sin embargo, no recomendamos usar este tipo de evento, ya que podría quitarse en una fecha futura.

Console

Si implementas con la consola de Google Cloud, puedes configurar un activador de Cloud Storage en la sección Activador.

Para Cloud Functions (2nd gen):
1. Haz clic en Agregar activador de Eventarc para agregar un activador de eventos. Se abrirá el panel Activador de Eventarc.
2. En el campo Proveedor de eventos, selecciona Cloud Storage.
3. En el campo Evento, selecciona un tipo de evento.
4. En el campo Bucket, haz clic en Explorar para seleccionar un bucket de Cloud Storage que el activador supervisará. Los cambios en los objetos de este bucket activarán llamadas a la función.
5. Selecciona o desmarca la casilla de verificación Reintentar en caso de error para controlar si las llamadas a funciones con errores se reintentan automáticamente. Consulta Reintenta las funciones controladas por eventos para obtener más información.
6. Haz clic en Guardar activador.
Nota: En Cloud Functions (2nd gen), también puedes configurar la cuenta de servicio que usa el activador de Eventarc creado. Consulta Activadores de Eventarc para obtener más información.
Para Cloud Functions (1st gen):
1. En el campo Tipo de activador, selecciona Cloud Storage.
2. En el campo Tipo de evento, selecciona un tipo de evento.
3. En el campo Bucket, haz clic en Explorar para seleccionar un bucket de Cloud Storage que el activador supervisará. Los cambios en los objetos de este bucket activarán llamadas a la función.
4. Selecciona o desmarca la casilla de verificación Reintentar en caso de error para controlar si las llamadas a funciones con errores se reintentan automáticamente. Consulta Reintenta las funciones controladas por eventos para obtener más información.

Entrega de eventos

Los activadores de Cloud Storage se implementan con las notificaciones de Pub/Sub para Cloud Storage. Los eventos están sujetos a las garantías de entrega de notificaciones de Pub/Sub.

Un bucket de Cloud Storage puede tener hasta 10 configuraciones de notificación definidas para activarse con un evento específico. Si superas los límites de notificaciones del bucket, se producirá un error como el siguiente cuando se implementen más funciones:

Cloud Storage bucket ...: Pub/Sub notification limit reached

Consulta Cuotas y límites de Cloud Storage para obtener más información.

Próximos pasos

Obtén más información sobre cómo escribir funciones controladas por eventos.
Aprende a implementar una función de Cloud Functions.
Consulta el instructivo de función de Cloud Storage para ver un ejemplo de escritura, implementación y llamada a una función con un activador de Cloud Storage.