Crea activadores con Cloud Storage

En Cloud Run, puedes activar servicios de Cloud Storage con Eventarc, en respuesta a los cambios en Cloud Storage.

Cuando especificas un activador de Cloud Storage para tu servicio, eliges un tipo de evento y un bucket de Cloud Storage. Como resultado de este activador, se llama a tu servicio cada vez que se produce un cambio en un objeto (archivo) dentro del bucket especificado.

Para que un evento en un bucket de Cloud Storage active tu servicio, el servicio y el bucket deben estar en el mismo proyecto de Google Cloud.

Cloud Run admite los siguientes tipos de eventos de Cloud Storage:

Event Tipo de evento Descripción
Objeto finalizado
  • google.cloud.storage.object.v1.finalized (a través de Eventarc)
 Ocurre cuando creas un objeto nuevo o reemplazas uno existente, y Cloud Storage 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 borras un objeto de forma permanente.
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 cambias los metadatos de un objeto existente.

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

Antes de comenzar

  1. Asegúrate de haber configurado un proyecto nuevo para Cloud Run, como se describe en la página de configuración.

  2. Habilita las APIs de Artifact Registry, Cloud Build, Cloud Run Admin, Eventarc, Cloud Logging, Pub/Sub y Cloud Storage:

    Habilita las APIs

Establece los roles requeridos

  1. Si eres el creador del proyecto, se te otorga el rol de propietario básico (roles/owner). De forma predeterminada, este rol de Identity and Access Management (IAM) incluye los permisos necesarios para obtener acceso completo a la mayoría de los recursos de Google Cloud, pero puedes omitir este paso.

    Si no eres el creador del proyecto, se deben otorgar los permisos necesarios en el proyecto a la principal correspondiente. Por ejemplo, una principal puede ser una Cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de procesamiento). Para obtener más información, consulta la página Roles y permisos para el destino del evento.

    Ten en cuenta que, de forma predeterminada, los permisos de Cloud Build incluyen permisos para subir y descargar artefactos de Artifact Registry.

    Permisos necesarios

    Para obtener los permisos que necesitas para configurar activadores de Cloud Storage, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

    Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

    También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

  2. Toma nota del recurso Compute Engine predeterminada, ya que la conectarás a un activador de Eventarc para representar la identidad del activador con fines de prueba. Esta cuenta de servicio se crea automáticamente después de habilitar o usar un servicio de Google Cloud que use Compute Engine, y con la siguiente formato de correo electrónico:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Reemplaza PROJECT_NUMBER por el número de proyecto de Google Cloud. Para encontrar el número del proyecto, ve a la página de bienvenida de la consola de Google Cloud o ejecuta el siguiente comando:

    gcloud projects describe PROJECT_ID --format='value(projectNumber)'

    Para entornos de producción, recomendamos crear una cuenta de servicio nueva y otorgarle una o más funciones de IAM que contengan los permisos mínimos requeridos y seguir el principio de privilegio mínimo.

  3. De forma predeterminada, solo los propietarios y los editores del proyecto, y los administradores y los invocadores de Cloud Run pueden llamar a los servicios de Cloud Run. Puedes controlar el acceso según el servicio. Sin embargo, para fines de prueba, otorga el rol de invocador de Cloud Run (run.invoker) en el proyecto de Google Cloud a la cuenta de servicio de Compute Engine. Esto otorga el rol en todos los servicios y trabajos de Cloud Run en un proyecto. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker

    Ten en cuenta que si creas un activador para un servicio autenticado de Cloud Run sin otorgar la función de invocador de Cloud Run, el activador se crea de forma correcta y está activo. Sin embargo, el activador no funcionará como se espera y aparecerá en el registro un mensaje similar al siguiente:

    The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
  4. Otorga el rol de receptor de eventos de Eventarc (roles/eventarc.eventReceiver) en el proyecto a la cuenta de servicio predeterminada de Compute Engine para que el activador de Eventarc pueda recibir eventos de proveedores de eventos. 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver
  5. Si habilitaste el agente de servicio de Cloud Pub/Sub el 8 de abril de 2021 o antes de esa fecha, para admitir las solicitudes de envío de Pub/Sub autenticadas, otorga el rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio. De lo contrario, este rol se otorga de forma predeterminada: 
    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator

Crea un activador para los servicios

Puedes especificar un activador después de implementar un servicio.

Haz clic en la pestaña para obtener instrucciones de la herramienta que elijas.

Console

  1. Implementa tu servicio de Cloud Run con contenedores o desde la fuente.

  2. En la consola de Google Cloud, ve a Cloud Run:

    Ir a Cloud Run

  3. En la lista de servicios, haz clic en un servicio existente.

  4. En la página de detalles del servicio, navega a la pestaña Activadores.

  5. Haz clic en Agregar activador y selecciona Activador de Cloud Storage.

  6. En el panel Activador de Eventarc, modifica los detalles del activador de la siguiente manera:

    1. En el campo Nombre del activador, ingresa un nombre para el activador o usa el nombre predeterminado.

    2. Selecciona un tipo de activador de la lista para especificar uno de los siguientes tipos de activador:

      • Fuentes de Google para especificar activadores para Pub/Sub, Cloud Storage, Firestore y otros proveedores de eventos de Google.

      • Terceros para integrarse a proveedores externos a Google que ofrecen una fuente de Eventarc. Para obtener más información, consulta Eventos de terceros en Eventarc.

    3. Selecciona Cloud Storage en la lista Proveedor de eventos para elegir un producto que proporcione el tipo de evento para activar tu servicio. Para ver la lista de proveedores de eventos, consulta Proveedores y destinos de eventos.

    4. Selecciona google.cloud.storage.object.v1.finalized en la lista Tipo de evento. La configuración del activador varía según el tipo de evento compatible. Para obtener más información, consulta Tipos de eventos.

    5. 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.

    6. Si el campo Región está habilitado, selecciona una ubicación para el activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso de Google Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu servicio en la misma región. Consulta Información sobre las ubicaciones de Eventarc para obtener más detalles sobre las ubicaciones de activadores de Eventarc.

    7. En el campo Cuenta de servicio, selecciona una cuenta de servicio. Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca el servicio. La cuenta de servicio del activador de Eventarc debe tener el permiso para invocar tu servicio. De forma predeterminada, Cloud Run usa la cuenta de servicio predeterminada de Compute Engine.

    8. De manera opcional, especifica la ruta de URL del servicio a la que se enviará la solicitud entrante. Esta es la ruta de acceso relativa en el servicio de destino al que se deben enviar los eventos del activador. Por ejemplo, /, /route, route y route/subroute.

    9. Una vez que hayas completado los campos obligatorios, haz clic en Guardar activador.

  7. Después de crear el activador, verifica su estado. Para esto, asegúrate de que haya una marca de verificación en la pestaña Activadores.

gcloud

  1. Implementa tu servicio de Cloud Run con contenedores o desde la fuente.

  2. Ejecuta el siguiente comando para crear un activador que filtre eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=SERVICE  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Reemplaza lo siguiente:

    • TRIGGER_NAME por el nombre de tu activador.

    • EVENTARC_TRIGGER_LOCATION con la ubicación del activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso de Google Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu servicio en la misma región. Para obtener más información, consulta Ubicaciones de Eventarc.

    • Reemplaza SERVICE por el nombre del servicio que implementas.

    • REGION por la región de Cloud Run del servicio

    • PROJECT_NUMBER por tu número de proyecto de Google Cloud Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca tu servicio. La cuenta de servicio del activador de Eventarc debe tener permiso para invocar tu servicio. De forma predeterminada, Cloud Run usa la cuenta de servicio de procesamiento predeterminada.

    • La marca event-filters especifica los filtros de eventos que supervisa el activador. Un evento que coincida con todos los filtros event-filters activa llamadas a tu servicio. Cada activador debe tener un tipo de evento compatible. No puedes cambiar el tipo de filtro de eventos después de crearlo. Para cambiar el tipo de filtro de eventos, debes crear un activador nuevo y borrar el anterior. De forma opcional, puedes repetir la marca --event-filters con un filtro compatible en el formato ATTRIBUTE=VALUE para agregar más filtros.

Crea un activador para funciones

Haz clic en la pestaña para obtener instrucciones de la herramienta que elijas.

Console

Cuando usas la consola de Google Cloud para crear una función, también puedes agregar un activador a ella. Sigue estos pasos para crear un activador para tu función:

  1. En la consola de Google Cloud ve a Cloud Run:

    Ir a Cloud Run

  2. Haz clic en Escribe una función y, luego, ingresa los detalles de la función. Para obtener más información sobre la configuración de funciones durante la implementación, consulta Cómo implementar funciones.

  3. En la sección Activador, haz clic en Agregar activador.

  4. Selecciona Activador de Cloud Storage.

  5. En el panel Activador de Eventarc, modifica los detalles del activador de la siguiente manera:

    1. Ingresa un nombre para el activador en el campo Nombre del activador o usa el nombre predeterminado.

    2. Selecciona un tipo de activador de la lista para especificar uno de los siguientes tipos de activador:

      • Fuentes de Google para especificar activadores para Pub/Sub, Cloud Storage, Firestore y otros proveedores de eventos de Google.

      • Terceros para integrarse a proveedores externos a Google que ofrecen una fuente de Eventarc. Para obtener más información, consulta Eventos de terceros en Eventarc.

    3. Selecciona Cloud Storage en la lista Proveedor de eventos para elegir un producto que proporcione el tipo de evento para activar tu función. Para ver la lista de proveedores de eventos, consulta Proveedores y destinos de eventos.

    4. Selecciona google.cloud.storage.object.v1.finalized en la lista Tipo de evento. La configuración del activador varía según el tipo de evento compatible. Para obtener más información, consulta Tipos de eventos.

    5. 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.

    6. Si el campo Región está habilitado, selecciona una ubicación para el activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso de Google Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu función en la misma región. Consulta Información sobre las ubicaciones de Eventarc para obtener más detalles sobre las ubicaciones de activadores de Eventarc.

    7. En el campo Cuenta de servicio, selecciona una cuenta de servicio. Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca la función. La cuenta de servicio del activador de Eventarc debe tener el permiso para invocar tu función. De forma predeterminada, Cloud Run usa la cuenta de servicio predeterminada de Compute Engine.

    8. De manera opcional, especifica la ruta de URL del servicio a la que se enviará la solicitud entrante. Esta es la ruta de acceso relativa en el servicio de destino al que se deben enviar los eventos del activador. Por ejemplo, /, /route, route y route/subroute.

  6. Una vez que hayas completado los campos obligatorios, haz clic en Guardar activador.

gcloud

Cuando creas una función con gcloud CLI, primero debes deploy y, luego, crear un activador. Sigue estos pasos para crear un activador para tu función:

  1. Ejecuta el siguiente comando en el directorio que contiene el código de muestra para implementar la función:

    gcloud beta run deploy FUNCTION \
        --source . \
        --function FUNCTION_ENTRYPOINT \
        --base-image BASE_IMAGE_ID \
        --region REGION

    Reemplaza lo siguiente:

    • Reemplaza FUNCTION por el nombre de la función que implementas. Puedes omitir este parámetro por completo, pero se te solicitará el nombre si lo haces.

    • FUNCTION_ENTRYPOINT por el punto de entrada a tu función en tu código fuente. Este es el código que ejecuta Cloud Run cuando se ejecuta tu función. El valor de esta marca debe ser un nombre de función o un nombre de clase completamente calificado que exista en tu código fuente.

    • BASE_IMAGE_ID por el entorno de la imagen base de tu función. Para obtener más detalles sobre las imágenes base y los paquetes incluidos en cada imagen, consulta Imágenes base de los entornos de ejecución.

    • REGION por la región de Google Cloud en la que deseas implementar tu función. Por ejemplo, us-central1.

  2. Ejecuta el siguiente comando para crear un activador que filtre eventos:

    gcloud eventarc triggers create TRIGGER_NAME  \
    --location=EVENTARC_TRIGGER_LOCATION \
    --destination-run-service=FUNCTION  \
    --destination-run-region=REGION \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Reemplaza lo siguiente:

    • TRIGGER_NAME por el nombre de tu activador.

    • EVENTARC_TRIGGER_LOCATION con la ubicación del activador de Eventarc. En general, la ubicación de un activador de Eventarc debe coincidir con la ubicación del recurso de Google Cloud que deseas supervisar para detectar eventos. En la mayoría de los casos, también debes implementar tu función en la misma región. Para obtener más información, consulta Ubicaciones de Eventarc.

    • Reemplaza FUNCTION por el nombre de la función que implementas.

    • REGION por la región de Cloud Run de la función.

    • PROJECT_NUMBER por tu número de proyecto de Google Cloud Los activadores de Eventarc están vinculados a cuentas de servicio para usarlos como identidad cuando se invoca la función. La cuenta de servicio del activador de Eventarc debe tener permiso para invocar tu función. De forma predeterminada, Cloud Run usa la cuenta de servicio de procesamiento predeterminada.

    • La marca event-filters especifica los filtros de eventos que supervisa el activador. Un evento que coincida con todos los filtros event-filters activa llamadas a tu función. Cada activador debe tener un tipo de evento compatible. No puedes cambiar el tipo de filtro de eventos después de crearlo. Para cambiar el tipo de filtro de eventos, debes crear un activador nuevo y borrar el anterior. De forma opcional, puedes repetir la marca --event-filters con un filtro compatible en el formato ATTRIBUTE=VALUE para agregar más filtros.

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