Activadores de Cloud Storage

En Cloud Run 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
  • google.cloud.storage.object.v1.finalized (a través de Eventarc)
 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
  • google.cloud.storage.object.v1.deleted (a través de Eventarc)
 Ocurre cuando un objeto se borra permanentemente.
Objeto archivado
  • google.cloud.storage.object.v1.archived (a través de Eventarc)
 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
  • google.cloud.storage.object.v1.metadataUpdated (a través de Eventarc)
 Ocurre cuando cambian los metadatos de un objeto existente.

Un activador de Cloud Storage se implementa como una función de CloudEvent, en la que 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.

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

Permisos

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

Implementación

Puedes especificar un activador de Cloud Storage cuando implementes una función. Consulta Implementa una Cloud Run Functions para obtener instrucciones generales sobre cómo implementar una función y, además, consulta la siguiente información adicional que está destinada específicamente a 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:

  gcloud functions deploy YOUR_FUNCTION_NAME 

  --gen2 

  --trigger-event-filters="type=EVENT_TYPE" 

  --trigger-event-filters="bucket=YOUR_STORAGE_BUCKET" 

  ...

Cuando implementes funciones, especifica el nombre del bucket solo sin el gs:// inicial; por ejemplo, --trigger-event-filters="bucket=my-bucket".

Console

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

  1. En el campo Tipo de activador, selecciona Cloud Storage.

  2. En el campo Tipo de evento, elige un evento de activación. El valor predeterminado es google.cloud.storage.object.v1.finalized.

    Para un evento de Cloud Storage que usa registros de auditoría de Cloud, consulta las instrucciones de configuración del activador para un activador de Eventarc.

  3. En el campo Bucket , haz clic en Explorar para seleccionar un bucket de Cloud Storage a fin de que el activador lo supervise. Los cambios en los objetos dentro de este bucket activarán llamadas a tu función.

  4. Selecciona o anula la selección de la casilla de verificación Reintentar en caso de error para controlar si Cloud Run Functions reintenta automáticamente una invocación de función con errores. Consulta Reintenta las funciones controladas por eventos para obtener más información.

  5. Haz clic en Más opciones para realizar una configuración adicional en tu activador:

    • En el campo Tipo de activador, especifica una de las Fuentes de Google, Personalizadas o De terceros:

      • Fuentes de Google te permite especificar activadores para Pub/Sub, Cloud Storage, Firestore y otros proveedores de eventos de Google. En el panel Activador de Eventarc, usa el campo Proveedor de eventos para seleccionar el producto que proporciona el tipo de evento que deseas que active la función. Luego, en el campo Evento, selecciona el evento que deseas usar como activador.

      • La opción Personalizado te permite producir y consumir eventos desde el código de la aplicación. Sigue las instrucciones del panel Activador de Eventarc para crear un canal. Un canal es un recurso que se usa como una canalización para entregar eventos personalizados de los productores a los consumidores. Los eventos personalizados se publican en un canal y un activador de Eventarc se suscribe a esos eventos.

      • La opción Terceros te permite integrarte a proveedores externos a Google que ofrecen una fuente de Eventarc. Consulta los eventos de terceros en Eventarc para obtener más detalles.

    • En el campo Evento, selecciona un evento activador. El valor predeterminado es google.cloud.storage.object.v1.finalized.

    • De manera opcional, en el campo Cuenta de servicio, selecciona una cuenta de servicio para usarla como identidad del activador de Eventarc. Consulta Identidad del activador para obtener más información.

  6. Haz clic en Guardar activador.

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