Pubblicare gli eventi direttamente

Avanzate

Puoi pubblicare un evento CloudEvents direttamente in un bus Eventarc Advanced in un formato supportato utilizzando Google Cloud CLI o inviando una richiesta all'API REST di pubblicazione di Eventarc. Puoi anche utilizzare le librerie client Eventarc per accedere alle API Eventarc da un linguaggio supportato.

Prima di iniziare

Prima di iniziare, assicurati di aver completato i seguenti passaggi:

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

Pubblicare direttamente

Il messaggio evento che pubblichi direttamente deve essere conforme alla specifica CloudEvents.

gcloud

1. Apri un terminale.

2. Puoi pubblicare eventi in un bus utilizzando il comando gcloud eventarc message-buses publish. Ad esempio:

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

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

   Oppure:
   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

   Sostituisci quanto segue:

   • BUS_NAME: l'ID o l'identificatore completo del bus a cui pubblicare l'evento.

   Devi utilizzare solo uno dei seguenti documenti:

   • AVRO_MESSAGE: il messaggio dell'evento in formato Avro secondo questa specifica.
   • JSON_MESSAGE: il messaggio dell'evento in formato JSON secondo questa specifica.
   • DATA_PAYLOAD: i dati di un evento pubblicato.

   Se utilizzi il flag --event-data, devi utilizzare anche quanto segue:

   • EVENT_ID: l'identificatore dell'evento. I produttori di eventi devono assicurarsi che source + id sia univoco per ogni evento distinto.
   • EVENT_SOURCE: l'origine evento di un evento pubblicato.
   • EVENT_TYPE: il tipo di evento correlato all'occorrenza di origine.

   Se utilizzi il flag --event-data, puoi facoltativamente utilizzare quanto segue:

   • EVENT_ATTRIBUTE: gli attributi di un evento pubblicato. Puoi ripetere il flag --event-attributes per aggiungere altri attributi.

     Tieni presente che gli eventi possono includere un numero qualsiasi di attributi CloudEvents personalizzati aggiuntivi con nomi distinti (noti anche come attributi di estensione).

Esempi:

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 REST

Per pubblicare un evento in un bus, utilizza il metodo projects.locations.messageBuses.publish.

Nota: nel ProtoMessage del corpo della richiesta, il campo protoData funziona come previsto solo quando il payload è specificamente un tipo di messaggio CloudEvent e non può essere utilizzato per messaggi di protocol buffer arbitrari. Per qualsiasi altro tipo di protocol buffer, devi serializzare il messaggio proto in byte e utilizzare invece il campo binaryData.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• Il nome completo della risorsa del bus nel formato projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME

  Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Google Cloud per il progetto bus.
  • LOCATION: la regione in cui viene eseguito il deployment del bus, ad esempio us-central1.
  • BUS_NAME: il nome del bus a cui pubblicare l'evento.
• SPEC_VERSION: la versione della specifica CloudEvents utilizzata dall'evento, ad esempio 1.0.
• EVENT_TYPE: il tipo di evento correlato all'occorrenza di origine.
• EVENT_SOURCE: l'origine evento di un evento pubblicato.
• EVENT_ID: l'identificatore dell'evento. I produttori devono assicurarsi che source + id sia univoco per ogni evento distinto.
• CONTENT_TYPE (facoltativo): il tipo di contenuti del valore data. Se un evento in formato JSON non ha l'attributo datacontenttype, si presume che i dati siano un valore JSON conforme al tipo di media application/json.
• DATA_PAYLOAD (facoltativo): il payload dell'evento codificato nel formato multimediale specificato da datacontenttype e conforme a dataschema quando questi attributi sono presenti.

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

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

Quindi esegui questo comando per inviare la richiesta 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: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
"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

Quindi esegui questo comando per inviare la richiesta 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

Explorer API (browser)

Copia il corpo della richiesta e apri la pagina di riferimento del metodo. Sul lato destro della pagina si apre il riquadro Explorer API. Puoi interagire con questo strumento per inviare richieste. Incolla il corpo della richiesta in questo strumento, compila gli altri campi obbligatori e fai clic su Esegui.

Se l'operazione va a buon fine, il server restituisce un codice di stato HTTP 200 OK e la risposta con un testo vuoto in formato JSON:

200 OK

{}

Passaggi successivi

• Pubblicare eventi da origini Google
• Trasformare gli eventi ricevuti
• Formattare gli eventi ricevuti