Publicar eventos en un trabajo de Cloud Run

Publicar eventos en un trabajo de Cloud Run

Avanzado

En esta guía de inicio rápido se muestra cómo publicar y recibir mensajes de eventos creando un bus avanzado de Eventarc y registrándote en tu proyecto de Google Cloud.

• Un bus actúa como un enrutador central que recibe mensajes de fuentes de eventos o que publican los proveedores.

• Una inscripción dirige los mensajes recibidos por el bus a uno o varios destinos a través de una pipeline de procesamiento.

En esta guía de inicio rápido, harás lo siguiente:

1. Despliega un trabajo de Cloud Run.

2. Crea un bus avanzado de Eventarc.

3. Crea un registro avanzado de Eventarc.

4. Publica un mensaje de evento en el bus.

5. Consulta los datos de eventos en los registros y confirma que el trabajo de Cloud Run se ha ejecutado correctamente.

Puedes completar esta guía de inicio rápido con la CLI de gcloud.

Antes de empezar

Es posible que las restricciones de seguridad definidas por tu organización te impidan completar los siguientes pasos. Para obtener información sobre cómo solucionar problemas, consulta el artículo Desarrollar aplicaciones en un entorno limitado Google Cloud .

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Run and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

Install the Google Cloud CLI.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Run and Eventarc APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

1. Actualiza los componentes de gcloud:

   gcloud components update

2. Inicia sesión con tu cuenta:

   gcloud auth login

3. Defina la variable de configuración que se usa en esta guía de inicio rápido:

   REGION=REGION

   Sustituye REGION por una ubicación admitida del autobús (por ejemplo, us-central1).

4. Si has creado el proyecto, se te asignará el rol básico Propietario (roles/owner). De forma predeterminada, este rol de gestión de identidades y accesos (IAM) incluye los permisos necesarios para acceder por completo a la mayoría de los recursos Google Cloud, por lo que puedes saltarte este paso.

   Si no eres el creador del proyecto, debes conceder los permisos necesarios al principal correspondiente. Por ejemplo, una entidad principal puede ser una cuenta de Google (para usuarios finales) o una cuenta de servicio (para aplicaciones y cargas de trabajo de computación).

   Permisos obligatorios

   Para obtener los permisos que necesitas para completar esta guía de inicio rápido, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

   • Cloud Run Developer (roles/run.developer)
   • Desarrollador de Eventarc (roles/eventarc.developer)
   • Administrador de bus de mensajes de Eventarc (roles/eventarc.messageBusAdmin)
   • Usuario con permiso para ver registros (roles/logging.viewAccessor)
   • Administrador de gestión de identidades y accesos del proyecto (roles/resourcemanager.projectIamAdmin)
   • Administrador de cuentas de servicio (roles/iam.serviceAccountAdmin)
   • Usuario de cuenta de servicio (roles/iam.serviceAccountUser)
   • Administrador de Uso de Servicio (roles/serviceusage.serviceUsageAdmin)

   Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

   También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

5. Para dar a Eventarc Advanced los permisos necesarios para ejecutar un trabajo de Cloud Run, pide a tu administrador que asigne el rol de IAM Invocador de Cloud Run (roles/run.invoker) en tu proyectoGoogle Cloud a una cuenta de servicio:
   1. Crea una cuenta de servicio. Para hacer pruebas, adjuntarás esta cuenta de servicio a una canalización avanzada de Eventarc para representar la identidad de la canalización.

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Sustituye SERVICE_ACCOUNT_NAME por el nombre de tu cuenta de servicio.
   2. Asigna el rol de roles/run.invoker gestión de identidades y accesos a la cuenta de servicio:

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/run.invoker

Desplegar un trabajo de Cloud Run

Despliega un trabajo de Cloud Run como destino de eventos. A diferencia de un servicio de Cloud Run, que escucha y atiende solicitudes, un trabajo de Cloud Run solo ejecuta sus tareas y se cierra cuando termina. Un trabajo no escucha ni sirve solicitudes.

Se admiten otros destinos de eventos, como un tema de Pub/Sub, Workflows u otro endpoint HTTP. Para obtener más información, consulta Proveedores y destinos de eventos.

Despliega un trabajo desde un contenedor de ejemplo con el comando gcloud run jobs deploy.

gcloud run jobs deploy JOB_NAME --image us-docker.pkg.dev/cloudrun/container/job:latest \
    --region=$REGION

Sustituye JOB_NAME por un nombre único para el trabajo de Cloud Run. Por ejemplo, my-job.

Crear un bus de Eventarc Advanced

Un bus recibe mensajes de eventos de una fuente de mensajes o publicados por un proveedor y actúa como un enrutador de mensajes.

Para obtener más información, consulta el artículo Crear un bus para enrutar mensajes.

Nota: Puedes crear un bus por Google Cloud proyecto por región admitida.

Crea un bus avanzado de Eventarc en tu proyecto con el comando gcloud eventarc message-buses create:

gcloud eventarc message-buses create BUS_NAME \
    --location=$REGION

Sustituye BUS_NAME por el ID de tu autobús o por un nombre completo, como my-bus.

Crear un registro de Eventarc Advanced

Una inscripción determina qué mensajes se enrutan a un destino. También especifica la canalización que se usa para configurar el destino de los mensajes de eventos. En este caso, el destino es un trabajo de Cloud Run.

Para obtener más información, consulta Crear un registro para recibir eventos.

Nota: La creación de una canalización puede tardar más de 10 minutos.

Cuando usas gcloud CLI, primero creas una canalización y, después, una inscripción:

1. Crea una canalización con el comando gcloud eventarc pipelines create:

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='https://REGION-run.googleapis.com/apis/run.googleapis.com/v1/namespaces/PROJECT_NUMBER/jobs/JOB_NAME:run',http_endpoint_message_binding_template='{"body": ""}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   Haz los cambios siguientes:

   • PIPELINE_NAME: el ID de la canalización o un nombre completo, como my-pipeline.
   • PROJECT_NUMBER: el número de tu proyecto Google Cloud . Para obtener el número de tu proyecto, ejecuta el siguiente comando:

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

   Ten en cuenta lo siguiente:

   • La clave http_endpoint_message_binding_template transforma el evento al formato que espera la API Admin de Cloud Run. Al definir un enlace de mensaje, debes configurar un formato de entrada para acceder a la carga útil.
   • La clave oauth_token_authentication_service_account especifica un correo de cuenta de servicio. Esta dirección de correo se usa para generar un token de OAuth que normalmente solo se usa al llamar a las APIs de Google alojadas en *.googleapis.com.

2. Para crear un registro, usa el comando gcloud eventarc enrollments create:

   gcloud eventarc enrollments create ENROLLMENT_NAME \
       --cel-match=MATCH_EXPRESSION \
       --destination-pipeline=PIPELINE_NAME \
       --message-bus=BUS_NAME \
       --message-bus-project=PROJECT_ID \
       --location=$REGION

   Haz los cambios siguientes:

   • ENROLLMENT_NAME: el ID de la inscripción o un nombre completo (por ejemplo, my-enrollment).

   • MATCH_EXPRESSION: la expresión coincidente de esta inscripción con CEL. Por ejemplo:

     "message.type == 'hello-world-type'"
     

Publicar un mensaje de evento en el bus

Para publicar un mensaje directamente en tu bus, usa el comando gcloud eventarc message-buses publish o envía una solicitud a la API REST de publicación de Eventarc. Para obtener más información, consulta Publicar eventos directamente.

El mensaje debe estar en formato CloudEvents, una especificación para describir datos de eventos de forma común. El elemento data es la carga útil de tu evento. En este campo se puede incluir cualquier JSON con el formato correcto. Para obtener más información sobre los atributos de contexto de CloudEvents, consulta el artículo Formato de evento.

A continuación, se muestran ejemplos de cómo publicar directamente un evento en un bus avanzado de Eventarc:

Ejemplo 1

Publica un evento en un bus mediante la CLI de gcloud y un --event-data y otras marcas de atributos de evento:

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

Ejemplo 2

Publica un evento en un bus como mensaje JSON mediante gcloud CLI y una marca --json-message:

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

Después de publicar un evento, deberías recibir el mensaje "Evento publicado correctamente".

Ver los datos de eventos en los registros de Cloud Run

Después de publicar un evento en tu bus avanzado de Eventarc, consulta los registros de tu trabajo de Cloud Run para verificar que el evento se ha recibido correctamente.

1. Filtra las entradas de registro y devuelve el resultado mediante el comando gcloud logging read:

   gcloud logging read 'textPayload: "hello-world-data"'
   

2. Busca una entrada de registro similar a la siguiente:

   insertId: 670808e70002b5c6477709ae
   labels:
   instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
   logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
   receiveTimestamp: '2025-10-06T21:15:22.988264020Z'
   resource:
   labels:
   ...
   type: cloud_run_revision
   textPayload: "[2025-10-06 21:15:22,676] INFO in server: Body: b'{\"key\": \"hello-world-data\"\
     }'"
   timestamp: '2025-10-06T21:15:22.675530Z'
   

   Nota: Si no ves ninguna entrada de registro, espera unos minutos y vuelve a ejecutar el comando gcloud logging read.

3. Confirma que el trabajo de Cloud Run se ha ejecutado correctamente con el comando gcloud run jobs describe:

   gcloud run jobs describe JOB_NAME \
       --region=$REGION
   

   Deberías obtener un resultado similar al siguiente:

   ✔ Job JOB_NAME in region us-central1
   Executed 1 time
   ...
   

Has creado correctamente un bus y un registro de Eventarc Advanced, has publicado un mensaje de evento en el bus y has verificado el resultado esperado en los registros del receptor de eventos.

Limpieza

Para evitar que se te siga facturando después de completar esta guía de inicio rápido, elimina los recursos que has creado:

1. Eliminar un trabajo de Cloud Run.

2. Elimina los recursos avanzados de Eventarc:

   1. Eliminar una inscripción.

   2. Eliminar una canalización

   3. Eliminar un autobús

También puede eliminar su Google Cloud proyecto para evitar que se le apliquen cargos. Al eliminar tu Google Cloud proyecto, se detendrá la facturación de todos los recursos utilizados en él.

Precaución: Eliminar un proyecto tiene los siguientes efectos:

• Se elimina todo el contenido del proyecto. Si has usado un proyecto que ya existía para las tareas de este documento, cuando lo elimines, también se eliminará cualquier otro trabajo que hayas realizado en él.
• Se pierden los IDs de proyecto personalizados. Cuando creaste este proyecto, es posible que hayas creado un ID de proyecto personalizado que quieras usar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, elimina los recursos seleccionados dentro del proyecto en lugar de eliminar todo el proyecto.

Si tienes previsto consultar varias arquitecturas, tutoriales o guías de inicio rápido, reutilizar los proyectos puede ayudarte a no superar los límites de cuota de proyectos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Siguientes pasos

• Publicar eventos de fuentes de Google
• Publicar eventos directamente
• Transformar eventos recibidos
• Dar formato a los eventos recibidos