Se usó la API de Cloud Translation para traducir esta página.

Cómo activar el procesamiento de eventos desde Cloud Storage con Eventarc y funciones de Cloud Run

1. Descripción general

En este lab, aprenderás a usar los eventos de bucket de Cloud Storage y Eventarc para activar el procesamiento de eventos. Usarás funciones de Cloud Run para analizar datos y procesar imágenes. La función usará la API de Vision de Google y guardará la imagen resultante en el bucket de Cloud Storage.

Qué aprenderás

Cómo compilar una canalización de procesamiento de imágenes

Configura buckets de Storage
Crea funciones de Cloud Run para leer y escribir objetos en Cloud Storage
Implementa un activador de Eventarc
Integra la API de Vision para detectar imágenes de comida
Prueba y valida la solución de extremo a extremo

Requisitos previos

Para este lab, se da por sentado que el usuario tiene conocimientos previos sobre los entornos de shell y la consola de Cloud.
Tener experiencia previa con Cloud Storage, funciones de Cloud Run o la API de Vision es útil, pero no es obligatorio.

2. Configuración y requisitos

Configuración del proyecto de Cloud

Accede a Google Cloud Console y crea un proyecto nuevo o reutiliza uno existente. Si aún no tienes una cuenta de Gmail o de Google Workspace, debes crear una.

El Nombre del proyecto es el nombre visible de los participantes de este proyecto. Es una cadena de caracteres que no se utiliza en las APIs de Google. Puedes actualizarla cuando quieras.
El ID del proyecto es único en todos los proyectos de Google Cloud y es inmutable (no se puede cambiar después de configurarlo). La consola de Cloud genera automáticamente una cadena única. Por lo general, no importa cuál sea. En la mayoría de los codelabs, deberás hacer referencia al ID de tu proyecto (suele identificarse como PROJECT_ID). Si no te gusta el ID que se generó, podrías generar otro aleatorio. También puedes probar uno propio y ver si está disponible. No se puede cambiar después de este paso y se usa el mismo durante todo el proyecto.
Recuerda que hay un tercer valor, un número de proyecto, que usan algunas APIs. Obtén más información sobre estos tres valores en la documentación.

A continuación, deberás habilitar la facturación en la consola de Cloud para usar las APIs o los recursos de Cloud. Ejecutar este codelab no costará mucho, tal vez nada. Para cerrar recursos y evitar que se generen cobros más allá de este instructivo, puedes borrar los recursos que creaste o borrar el proyecto. Los usuarios nuevos de Google Cloud son aptos para participar en el programa Prueba gratuita de $300.

Activar Cloud Shell

Para activar Cloud Shell, haz clic en el ícono que se encuentra a la derecha de la barra de búsqueda.

Configuración del entorno

Ejecuta los siguientes comandos en la terminal de Cloud Shell para crear variables de entorno relacionadas con el proyecto y los recursos.

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NAME=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export REGION=us-east1 
export UPLOAD_BUCKET_NAME=menu-item-uploads-$PROJECT_ID
export UPLOAD_BUCKET=gs://menu-item-uploads-$PROJECT_ID
export BUCKET_THUMBNAILS=gs://menu-item-thumbnails-$PROJECT_ID
export MENU_SERVICE_NAME=menu-service
export USER_EMAIL=$(gcloud config list account --format "value(core.account)")

Habilita las APIs necesarias para el lab

gcloud services enable \
    vision.googleapis.com \
    cloudfunctions.googleapis.com \
    pubsub.googleapis.com \
    cloudbuild.googleapis.com \
    logging.googleapis.com \
    eventarc.googleapis.com \
    artifactregistry.googleapis.com \
    run.googleapis.com \
    --quiet

Clona el repositorio

git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git && cd cymbal-eats/cloud-functions

3. Configura buckets de Cloud Storage

Crea buckets de almacenamiento

Crea buckets de Cloud Storage de carga y miniaturas para tu canalización de procesamiento de imágenes.

Usa el comando gsutil mb y un nombre único para crear dos buckets:

Bucket de carga al que se subirán las imágenes primero
Bucket de miniaturas para almacenar las imágenes de miniaturas generadas

Crea un bucket para subir imágenes nuevas:

gsutil mb -p $PROJECT_ID -l $REGION $UPLOAD_BUCKET

Resultado de ejemplo:

Creating gs://menu-item-uploads-cymbal-eats-8399-3119/...

Crea un bucket para almacenar las miniaturas generadas:

gsutil mb -p $PROJECT_ID -l $REGION $BUCKET_THUMBNAILS

Resultado de ejemplo:

Creating gs://menu-item-thumbnails-cymbal-eats-8399-3119/...

Actualiza los permisos del bucket

Actualiza los permisos del bucket de almacenamiento para permitirles a los usuarios permisos de lectura.

Usa el comando gsutil iam ch para otorgar permiso de lectura y escritura a los objetos de tu bucket:

gsutil iam ch allUsers:objectViewer $UPLOAD_BUCKET
gsutil iam ch allUsers:objectViewer $BUCKET_THUMBNAILS

Ejemplo de resultado:

Updated IAM policy for project [cymbal-eats-8399-3119].
[...]

4. Configurar cuentas de servicio

Crea una cuenta de servicio personalizada para que Cloud Function procese las miniaturas:

export CF_SERVICE_ACCOUNT=thumbnail-service-sa
gcloud iam service-accounts create ${CF_SERVICE_ACCOUNT}

Otorga el rol artifactregistry.reader para permitir operaciones de lectura desde Artifact Registry:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.reader"

Otorga el rol storage.objectCreator para permitir el almacenamiento de imágenes generadas en el bucket de miniaturas:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/storage.objectCreator"

Otorga el rol run.invoker para permitir la invocación del servicio de Cloud Run:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/run.invoker"

Otorga el rol eventarc.eventReceiver para permitir recibir eventos de los proveedores:

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/eventarc.eventReceiver"

Otorga el rol pubsub.publisher a la cuenta de servicio de Cloud Storage. Esto permitirá que la cuenta de servicio publique eventos cuando se suban imágenes al bucket.

GCS_SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
    --member "serviceAccount:$GCS_SERVICE_ACCOUNT" \
    --role "roles/pubsub.publisher"

5. Descripción general de la función de procesamiento de imágenes

Crea una función para descargar una imagen de Cloud Storage, cambiar su tamaño y volver a subirla a Cloud Storage. La función llamará a la API de Vision para asignar una etiqueta de descripción a la imagen. La función verificará la etiqueta de descripción. Si la etiqueta identifica la imagen como "Comida", se enviará un evento al servicio de menú para actualizar la imagen y la miniatura del elemento de menú.

Activa una función

Las funciones de Cloud Storage se basan en notificaciones de Pub/Sub desde Cloud Storage y admiten tipos de eventos similares:

En este lab, implementarás y activarás una función cuando se finalice un objeto en Cloud Storage.

Finalización del objeto

Los eventos de finalización de objeto se activan cuando una operación de "escritura" de un objeto de Cloud Storage se finaliza correctamente. En particular, esto significa que crear un objeto nuevo o reemplazar uno existente activa este evento. Este activador ignora las operaciones de actualización de archivo y metadatos.

6. Integra Cloud Storage

como tus objetos, en Google Cloud. Un objeto es un dato inmutable que consta de un archivo de cualquier formato. Los objetos se almacenan en contenedores llamados buckets. Todos los buckets están asociados a un proyecto que, a su vez, se pueden agrupar en una organización. Las bibliotecas cliente y las APIs facilitan la integración con Cloud Storage.

En este lab, usarás la biblioteca cliente para leer y escribir objetos en Cloud Storage.

Instala la biblioteca cliente

Las bibliotecas cliente de Cloud están disponibles en muchos lenguajes de programación populares. Para comenzar a usar las bibliotecas, debes instalar la biblioteca cliente.

Usa la biblioteca cliente

Los detalles de la implementación dependen en gran medida del lenguaje de programación. Para usar la biblioteca cliente en tu aplicación, el primer paso es importar las dependencias de Cloud Storage. Por ejemplo, en el proyecto de Node.js, las importaciones se agregan al archivo package.json. En el siguiente fragmento, se muestra el aviso del archivo package.json de este lab.

package.json

{
    "name": "thumbnail-service",
    "version": "0.1.0",
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0",
      "@google-cloud/storage": "^5.18.2",
      "@google-cloud/vision": "^2.4.2",
        ...
    }
  }

Registra una devolución de llamada de CloudEvent

Registra una devolución de llamada de CloudEvent con el framework de Functions que activará Cloud Storage cuando se suba una imagen nueva al bucket.

index.js

functions.cloudEvent('process-thumbnails', async (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);
    ...

Crea un objeto de referencia de almacenamiento

Después de importar las bibliotecas cliente, deberás crear un nuevo cliente de almacenamiento y los buckets con los que interactuará tu aplicación.

index.js

const storage = new Storage();
const bucket = storage.bucket(file.bucket);
const thumbBucket = storage.bucket(process.env.BUCKET_THUMBNAILS);

Descarga objetos de Cloud Storage

index.js

await bucket.file(file.name).download({
            destination: originalFile
        });

Sube objetos a Cloud Storage

Puedes enviar solicitudes de carga a Cloud Storage de tres maneras: carga multiparte de API de XML, carga multiparte reanudable o carga de una sola solicitud. Para cargas más grandes o cargas de transmisión, usa cargas reanudables. Con la API de XML, los archivos se suben en partes y se ensamblan como un solo objeto. Para objetos más pequeños, usa cargas de una sola solicitud.

El siguiente código sube una imagen a Cloud Storage con una carga de una sola solicitud.

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. Integra la API de Vision

Cloud Vision permite a los desarrolladores integrar con facilidad funciones de detección de visión en las aplicaciones, como el etiquetado de imágenes, la detección de rostros y puntos de referencia, el reconocimiento óptico de caracteres (OCR) y el etiquetado de contenido explícito.

Instala la biblioteca cliente

Las bibliotecas cliente de Cloud están disponibles en muchos lenguajes de programación populares. Para comenzar a usar las bibliotecas, debes instalar la biblioteca cliente.

Crea un cliente de Image Annotator

Para acceder a las APIs de Google con los SDK de clientes oficiales, crea un objeto de servicio basado en el documento de descubrimiento de la API, que describe la API al SDK. Tendrás que recuperarlo desde el servicio de descubrimiento de la API de Vision con tus credenciales.

index.js

const client = new vision.ImageAnnotatorClient();

Compila una solicitud a la API de Vision

La API de Vision puede realizar una detección de características en un archivo de imagen si envías el contenido del archivo de imagen como una cadena codificada en base64 en el cuerpo de la solicitud.

Para compilar una solicitud con el recurso de imágenes y anotar tu imagen. Una solicitud a esta API toma la forma de un objeto con una lista de solicitudes. Todos los elementos de esta lista incluyen dos tipos de información:

Los datos de la imagen codificados en base64
Una lista de características para las que querrías tener anotaciones respecto de la imagen

index.js

        const client = new vision.ImageAnnotatorClient();
        const visionRequest = {
            image: { source: { imageUri: `gs://${file.bucket}/${file.name}` } },
            features: [
                { type: 'LABEL_DETECTION' },
            ]
        };
        const visionPromise = client.annotateImage(visionRequest);

8. Implementa Cloud Run Functions

Este servicio de cambio de tamaño de imágenes forma parte del sistema más grande de Cymbal Eats. En esta sección, implementarás solo los componentes relacionados con la función de procesamiento de imágenes. La instalación completa incorpora una IU para subir la imagen y una solicitud descendente para almacenar los metadatos resultantes. Esas funciones no se instalan como parte de este lab.

Se crearán los siguientes componentes durante la implementación de la función:

Funciones de Cloud Run
Activador de Eventarc
Tema y suscripción de Pub/Sub

En la terminal de Cloud Shell, ejecuta el siguiente comando para implementar funciones de Cloud Run con un bucket de activador en menu-item-uploads-$PROJECT_ID:

Para implementar una función de Cloud Run directamente en Cloud Run, primero debes implementar la función y, luego, crear un activador para ella.

Implementa las funciones de Cloud Run:

gcloud beta run deploy process-thumbnails \
      --source=thumbnail \
      --function process-thumbnails \
      --region $REGION \
      --base-image google-22-full/nodejs20 \
      --no-allow-unauthenticated \
      --project=$PROJECT_ID \
--service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
--set-env-vars=BUCKET_THUMBNAILS=$BUCKET_THUMBNAILS,MENU_SERVICE_URL=$MENU_SERVICE_URL \
  --max-instances=1 \
  --quiet

Resultado de ejemplo:

Done.                                                                                                                                                                                    
Service [process-thumbnails] revision [process-thumbnails-00001-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://process-thumbnails-000000000.us-east1.run.app

Crea el activador:

gcloud eventarc triggers create process-thumbnails-trigger \
     --location=$REGION \
     --destination-run-service=process-thumbnails \
    --destination-run-region=$REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$UPLOAD_BUCKET_NAME" \
     --service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com"

Resultado de ejemplo:

Creating trigger [process-thumbnails-trigger] in project [qwiklabs-gcp-02-53f8532696e1], location [us-east1]...done.                                                                     
WARNING: It may take up to 2 minutes for the new trigger to become active.

Si la implementación del activador falla debido a un problema de permisos, espera a que se propaguen los cambios de IAM del paso anterior. Por lo general, tarda entre 1 y 2 minutos. Luego, vuelve a intentar la implementación.

Ejemplo de salida de error:

...If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent...
[...]

En Cloud Console, revisa el servicio de Cloud Run que se creó para la función:

En la consola de Cloud, revisa el activador de Eventarc que se creó para la función:

En la consola de Cloud, revisa el Tema y la Suscripción de Pub/Sub que se crearon para el activador de Eventarc:

9. Prueba y valida la solución de extremo a extremo

Sube una foto nueva a Cloud Storage y supervisa el progreso de la canalización a medida que se analizan las imágenes. Para probar la solución de extremo a extremo, supervisarás los registros de Cloud Functions.

Sube una imagen

Guarda esta imagen en tu máquina local.
Cambia el nombre del archivo a 1.jpg.
Abre la consola de Cloud Storage.
Haz clic en el bucket menu-item-uploads-....
Haz clic en SUBIR ARCHIVOS.
Sube 1.jpg al bucket de almacenamiento.
En la consola de Cloud, navega a Cloud Run.
Haz clic en process-thumbails.
Haz clic en la pestaña REGISTROS.

Navega al bucket menu-item-thumbnails-$PROJECT_ID Cloud Storage.
Verifica que la imagen de miniatura se haya creado en el bucket de miniaturas

Subir una imagen que no sea de comida

Para verificar que la función funcione correctamente, subirás una imagen que no contenga un objeto que se clasificaría como un elemento "Comida".

Guarda esta imagen en tu máquina local.
Cambia el nombre del archivo a 2.jpg.
Abre la consola de Cloud Storage.
Haz clic en el bucket menu-item-uploads-....
Haz clic en SUBIR ARCHIVOS.
Sube 2.jpg al bucket de almacenamiento.
En la consola de Cloud, navega a Cloud Run.
Haz clic en process-thumbails.
Haz clic en la pestaña REGISTROS.

10. ¡Felicitaciones!

¡Felicitaciones! Completaste el lab.

¿Qué sigue?

Explora otros codelabs de Cymbal Eats:

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.