Publica eventos directamente

Avanzado

Puedes publicar un evento de CloudEvents directamente en un bus de Eventarc Advanced en un formato compatible con Google Cloud CLI o enviando una solicitud a la API de REST de Eventarc Publishing. También puedes usar las bibliotecas cliente de Eventarc para acceder a las APIs de Eventarc desde un lenguaje compatible.

Antes de comenzar

Antes de comenzar, asegúrate de haber completado los siguientes pasos:

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.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

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 role (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 Eventarc and Eventarc Publishing 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

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

To initialize the gcloud CLI, run the following command:

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 role (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 Eventarc and Eventarc Publishing 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

Publicar directamente

El mensaje de evento que publiques directamente debe cumplir con la especificación de CloudEvents.

gcloud

1. Abre una terminal.

2. Puedes publicar eventos en un bus con el comando gcloud eventarc message-buses publish. Por ejemplo:

   gcloud eventarc message-buses publish BUS_NAME \
       --avro-message=AVRO_MESSAGE

   O bien:
   gcloud eventarc message-buses publish BUS_NAME \
       --json-message=JSON_MESSAGE

   O bien:
   gcloud eventarc message-buses publish BUS_NAME \
       --event-data=DATA_PAYLOAD \
       --event-id=EVENT_ID \
       --event-source=EVENT_SOURCE \
       --event-type=EVENT_TYPE \
       --event-attributes=EVENT_ATTRIBUTE

   Reemplaza lo siguiente:

   • BUS_NAME: Es el ID o el identificador completamente calificado del bus en el que se publicará el evento.

   Solo debes usar uno de los siguientes documentos:

   • AVRO_MESSAGE: Es el mensaje del evento en formato Avro según esta especificación.
   • JSON_MESSAGE: Es el mensaje del evento en formato JSON según esta especificación.
   • DATA_PAYLOAD: Son los datos de un evento publicado.

   Si usas la marca --event-data, también debes usar lo siguiente:

   • EVENT_ID: Es el identificador del evento. Los productores de eventos deben asegurarse de que source + id sea único para cada evento distinto.
   • EVENT_SOURCE: Es la fuente de eventos de un evento publicado.
   • EVENT_TYPE: Es el tipo de evento relacionado con el suceso original.

   Si usas la marca --event-data, también puedes usar las siguientes opciones:

   • EVENT_ATTRIBUTE: Son los atributos de un evento publicado. Puedes repetir la marca --event-attributes para agregar más atributos.

     Ten en cuenta que los eventos pueden incluir cualquier cantidad de atributos personalizados adicionales de CloudEvents con nombres distintos (también conocidos como atributos de extensión).

Ejemplos:

gcloud eventarc message-buses publish my-bus \
    --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"

gcloud eventarc message-buses publish my-bus --json-message='{
    "specversion" : "1.0",
    "type" :"com.example.someevent",
    "source" : "google.cloud.storage.object.v1.finalized",
    "id" : "A234-1234-1234",
    "time" : "2024-04-05T17:31:00Z",
    "bucket" : "bucketName",
    "datacontenttype" : "application/json",
    "data":{"key": "value"}
}'

API de REST

Para publicar un evento en un bus, usa el método projects.locations.messageBuses.publish.

Nota: En el ProtoMessage del cuerpo de la solicitud, el campo protoData solo funciona según lo esperado cuando la carga útil es específicamente un tipo de mensaje CloudEvent y no se puede usar para mensajes de búfer de protocolo arbitrarios. Para cualquier otro tipo de búfer de protocolo, debes serializar tu mensaje .proto en bytes y usar el campo binaryData.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

• Nombre completo del recurso del colectivo en el formato projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME

  Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud para el proyecto de autobús.
  • LOCATION: La región en la que se implementa el colectivo, por ejemplo, us-central1.
  • BUS_NAME: Es el nombre del bus en el que se publicará el evento.
• SPEC_VERSION: Es la versión de la especificación de CloudEvents que usa el evento, por ejemplo, 1.0.
• EVENT_TYPE: Es el tipo de evento relacionado con el suceso original.
• EVENT_SOURCE: Es la fuente del evento de un evento publicado.
• EVENT_ID: Es el identificador del evento. Los productores deben asegurarse de que source + id sea único para cada evento distinto.
• CONTENT_TYPE (opcional): Es el tipo de contenido del valor de data. Si un evento con formato JSON no tiene un atributo datacontenttype, se supone que los datos son un valor JSON que cumple con el tipo de medio application/json.
• DATA_PAYLOAD (opcional): Es la carga útil del evento codificada en el formato de medios especificado por datacontenttype y que se ajusta a dataschema cuando esos atributos están presentes.

Cuerpo JSON de la solicitud:

{
"jsonMessage":
  "{\"specversion\":\"SPEC_VERSION\",
  \"type\":\"EVENT_TYPE\",
  \"source\":\"EVENT_SOURCE\",
  \"id\":\"EVENT_ID\",
  \"datacontenttype\":\"CONTENT_TYPE\",
  \"data\":\"DATA_PAYLOAD\"}"
}

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

cat > request.json << 'EOF'
{
"jsonMessage":
  "{\"specversion\":\"SPEC_VERSION\",
  \"type\":\"EVENT_TYPE\",
  \"source\":\"EVENT_SOURCE\",
  \"id\":\"EVENT_ID\",
  \"datacontenttype\":\"CONTENT_TYPE\",
  \"data\":\"DATA_PAYLOAD\"}"
}
EOF

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://eventarcpublishing.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME:publish"

PowerShell (Windows)

Nota: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

@'
{
"jsonMessage":
  "{\"specversion\":\"SPEC_VERSION\",
  \"type\":\"EVENT_TYPE\",
  \"source\":\"EVENT_SOURCE\",
  \"id\":\"EVENT_ID\",
  \"datacontenttype\":\"CONTENT_TYPE\",
  \"data\":\"DATA_PAYLOAD\"}"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://eventarcpublishing.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME:publish" | Select-Object -Expand Content

Explorador de APIs (navegador)

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

Si la operación se realiza correctamente, el servidor devuelve un código de estado HTTP 200 OK y el cuerpo de respuesta vacío en formato JSON:

200 OK

{}

¿Qué sigue?

• Publica eventos de fuentes de Google
• Transforma los eventos recibidos
• Cómo dar formato a los eventos recibidos