Pubblicare e ricevere eventi creando un bus e una registrazione (console)

Pubblicare e ricevere eventi creando un bus e una registrazione (console)

Avanzate

Preview — Eventarc Advanced

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Questa guida rapida illustra come pubblicare e ricevere messaggi di eventi creando un bus Eventarc Advanced e una registrazione nel tuo progetto Google Cloud.

• Un bus ti consente di centralizzare il flusso di messaggi nel sistema e funge da router. Riceve messaggi di eventi da un'origine messaggio o pubblicati da un fornitore e li valuta in base a una registrazione.

• Una registrazione identifica un abbonamento a un determinato bus e definisce i criteri di corrispondenza per i messaggi, in modo che vengano instradati di conseguenza a una o più destinazioni.

In questa guida rapida:

1. Crea una subnet e abilita l'accesso privato Google.

2. Creare un collegamento di rete.

3. Crea un repository standard Artifact Registry.

4. Eseguire il deployment di un servizio di ricezione di eventi in Cloud Run.

5. Crea un bus Eventarc Advanced.

6. Crea una registrazione Eventarc Advanced.

7. Pubblica un messaggio di evento sul bus.

8. Visualizza i dati sugli eventi nei log di Cloud Run.

Puoi completare la maggior parte dei passaggi di questa guida rapida utilizzando la console Google Cloud. Per completare tutti i passaggi utilizzando Google Cloud CLI, consulta Pubblicare e ricevere eventi creando un bus e una registrazione (gcloud CLI).

Prima di iniziare

I vincoli di sicurezza definiti dalla tua organizzazione potrebbero impedirti di completare i passaggi seguenti. Per informazioni sulla risoluzione dei problemi, vedi Sviluppare applicazioni in un ambiente Google Cloud vincolato.

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

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   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.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs.

   Enable the APIs

8. Alcuni passaggi di questa guida rapida richiedono l'utilizzo dell'interfaccia a riga di comando gcloud:
   1. Configura gcloud CLI in uno dei seguenti ambienti di sviluppo:

      Cloud Shell

      Per utilizzare un terminale online con gcloud CLI già configurato, attiva Cloud Shell:

      Nella parte inferiore di questa pagina viene avviata una sessione di Cloud Shell e visualizzato un prompt della riga di comando. L'inizializzazione della sessione può richiedere alcuni secondi.

      Shell locale

      Per utilizzare un ambiente di sviluppo locale:

      1. Installa la gcloud CLI.
      2. Inizializza la gcloud CLI.
   2. Seleziona il tuo progetto Google Cloud:

      gcloud config set project PROJECT_ID

      Sostituisci PROJECT_ID con il nome del progetto Google Cloud.

   3. Aggiorna i componenti di gcloud:

      gcloud components update

   4. Accedi utilizzando il tuo account:

      gcloud auth login

   5. Imposta la variabile di configurazione utilizzata in questa guida rapida:

      REGION=us-central1

9. Se sei il creator del progetto, ti viene assegnato il ruolo di proprietario di base (roles/owner). Per impostazione predefinita, questo ruolo IAM include le autorizzazioni necessarie per l'accesso completo alla maggior parte delle risorse e puoi saltare questo passaggio. Google Cloud

   Se non sei il creator del progetto, le autorizzazioni richieste devono essere concesse al principale appropriato. Ad esempio, un'entità può essere un Account Google (per gli utenti finali) o un account di servizio (per le applicazioni e i carichi di lavoro di calcolo).

   Tieni presente che per impostazione predefinita, le autorizzazioni di Cloud Build includono le autorizzazioni per caricare e scaricare gli elementi di Artifact Registry.

   Autorizzazioni obbligatorie

   Per ottenere le autorizzazioni necessarie per completare questa guida introduttiva, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

   • Editor Cloud Build (roles/cloudbuild.builds.editor)
   • Amministratore Cloud Run (roles/run.admin)
   • Eventarc Developer (roles/eventarc.developer)
   • Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin)
   • Logs View Accessor (roles/logging.viewAccessor)
   • Amministratore IAM del progetto (roles/resourcemanager.projectIamAdmin)
   • Amministratore account di servizio (roles/iam.serviceAccountAdmin)
   • Utente account di servizio (roles/iam.serviceAccountUser)
   • Amministratore utilizzo servizio (roles/serviceusage.serviceUsageAdmin)

   Per ulteriori informazioni sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

   Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

10. Concedi i ruoli del progetto all'account di servizio predefinito di Compute Engine. Questi ruoli sono necessari per creare ed eseguire il deployment dell'immagine container.
    1. Nella console Google Cloud, vai alla pagina IAM.
       

       Vai a IAM

    2. Per modificare i ruoli per l'account di servizio se sono già presenti ruoli nella risorsa, trova una riga contenente l'entità.

       o

       Per concedere i ruoli all'account di servizio quando non ne ha nessuno sulla risorsa, fai clic su Concedi accesso, quindi inserisci l'identificatore per l'account di servizio predefinito di Compute Engine con il seguente modulo:

       [e-mail]

       Sostituisci PROJECT_NUMBER con il numero Google Cloud del tuo progetto. Puoi trovare il numero del progetto nella pagina Welcome della console Google Cloud.

    3. Fai clic su Modifica entità nella riga corrispondente.
    4. Fai clic su Aggiungi ruolo o su Aggiungi un altro ruolo.
    5. Nell'elenco Seleziona un ruolo, filtra e seleziona i seguenti ruoli:
       • Artifact Registry Writer: per caricare gli elementi di Artifact Registry
       • Logs Writer: per scrivere i log in Cloud Logging
       • Utente dell'oggetto di archiviazione: per accedere agli oggetti Cloud Storage
    6. Fai clic su Salva.
11. Per impostazione predefinita, solo i proprietari del progetto, gli editor del progetto, gli amministratori e gli invocatori di Cloud Run possono chiamare i servizi Cloud Run. Per configurare l'autenticazione, concedi il ruolo invocatore di Cloud Run nel tuo progetto Google Cloud a un account di servizio. Per scopi di test, collegherai questo account di servizio a una pipeline Eventarc Advanced per rappresentare l'identità della pipeline.
    1. Nella console Google Cloud, vai alla pagina Account di servizio.
       

       Vai ad Account di servizio

    2. Fai clic su Crea account di servizio.
    3. Inserisci un nome account di servizio.
    4. Fai clic su Crea e continua.
    5. Nell'elenco Seleziona un ruolo, filtra per il ruolo Cloud Run Invoker e selezionalo.
    6. Fai clic su Fine.

    Tieni presente che puoi configurare chi può accedere al tuo servizio Cloud Run in uno dei seguenti modi:

    • Concedi l'autorizzazione a gruppi o account di servizio selezionati per consentire l'accesso al servizio. Tutte le richieste devono avere un'intestazione di autorizzazione HTTP contenente un token OpenID Connect firmato da Google per uno degli account di servizio autorizzati. Questo è il modo in cui l'accesso è configurato in questa guida rapida.
    • Concedi l'autorizzazione a allUsers per permitirgli di consentire l'accesso non autenticato.

    Per ulteriori informazioni, consulta Controllo dell'accesso per Cloud Run.

Crea una subnet e abilita l'accesso privato Google

A meno che non crei un criterio dell'organizzazione che lo vieti, i nuovi Google Cloud progetti iniziano con una rete Virtual Private Cloud (VPC) predefinita (una rete VPC in modalità automatica) con una sottorete (subnet) in ogni regione. Alle subnet sono associati intervalli di indirizzi IP.

Poiché indirizzi i messaggi a una destinazione Cloud Run utilizzando un indirizzo DNS, devi attivare l'accesso privato Google sulla subnet utilizzata nel collegamento di rete; in caso contrario, l'indirizzo DNS non può essere risolto. Per ulteriori informazioni sulla rete privata e su Cloud Run, consulta Ricevere richieste dalle reti VPC.

Crea una subnet nella rete predefinita del progetto e abilita Accesso privato Google:

1. Nella console Google Cloud, vai alla pagina Reti VPC.

   Vai a Reti VPC

2. Nell'elenco delle reti VPC, fai clic sul nome predefinito.

3. Nella pagina Dettagli rete VPC, fai clic sulla scheda Subnet.

4. Fai clic su Aggiungi subnet.

5. Nel riquadro Aggiungi una subnet, segui questi passaggi:

   1. Inserisci un Nome, ad esempio my-subnet.
   2. Nell'elenco Regione, seleziona us-central1.
   3. Inserisci un intervallo IPv4 principale per la subnet, ad esempio 10.8.0.0/24.
   4. Per Accesso privato Google, seleziona On.
   5. Accetta tutti gli altri valori predefiniti.
   6. Fai clic su Aggiungi.

Gli intervalli di indirizzi IP delle subnet devono essere univoci e non devono sovrapporsi all'interno di una rete VPC e di una rete VPC in peering. Per ulteriori informazioni sui tipi di subnet e sugli intervalli di subnet validi, consulta Subnet.

Crea un collegamento di rete

Un collegamento di rete è una risorsa che consente a una rete VPC producer di avviare connessioni a una rete VPC consumer. Per pubblicare eventi, Eventarc Advanced utilizza il collegamento di rete per stabilire una connessione all'endpoint ospitato in una rete VPC.

Crea un collegamento di rete nella stessa rete e nella stessa regione contenente l'endpoint di destinazione dell'evento e che accetti automaticamente le connessioni da qualsiasi interfaccia Private Service Connect che fa riferimento al collegamento di rete:

1. Nella console Google Cloud, vai a Private Service Connect.

   Vai a Private Service Connect

2. Fai clic sulla scheda Componenti aggiuntivi di rete.

3. Fai clic su Crea collegamento di rete.

4. Inserisci un Nome, ad esempio my-network-attachment.

5. Nell'elenco Rete, seleziona valore predefinito.

6. Nell'elenco Regione, seleziona us-central1 (Iowa).

7. Nell'elenco Subnet, seleziona la subnet creata in precedenza.

8. Fai clic su Accetta automaticamente le connessioni per tutti i progetti.

9. Fai clic su Crea collegamento di rete.

Creare un repository standard Artifact Registry

Crea un repository standard di Artifact Registry per archiviare l'immagine del contenitore.

1. Nella console Google Cloud, vai alla pagina Repositori.

   Vai a Repository

2. Fai clic su Crea repository.

3. Inserisci un Nome, ad esempio my-repo.

   Per ogni posizione del repository in un progetto, i nomi dei repository devono essere univoci.

4. Per il Formato del repository, seleziona Docker.

5. Nell'elenco Regione, seleziona us-central1 (Iowa).

6. Accetta tutti gli altri valori predefiniti.

7. Fai clic su Crea.

Esegui il deployment di un servizio di ricezione di eventi in Cloud Run

Esegui il deployment di un servizio Cloud Run che registri i contenuti di un evento. Questo servizio è accessibile solo dalle reti VPC nello stesso progetto e l'URL del servizio non è direttamente accessibile perché il servizio consente solo chiamate autenticate.

1. Nel terminale, clona il repository GitHub:

   git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

2. Passa alla directory che contiene il codice di esempio di Cloud Run:

   cd eventarc-samples/eventarc-advanced-quickstart/

3. Crea un'immagine container Docker ed eseguine il push nel tuo repository:

   gcloud builds submit \
       --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1

   Sostituisci REPOSITORY con il nome del repository Artifact Registry.

4. Esegui il deployment dell'immagine container in Cloud Run:

   1. Nella console Google Cloud, vai alla pagina Cloud Run.

      Vai a Cloud Run

   2. Fai clic su Esegui il deployment del contenitore > Servizio.

   3. Seleziona Esegui il deployment di una revisione da un'immagine container esistente.

   4. Per l'URL immagine container, fai clic su Seleziona per specificare l'immagine container di Artifact Registry che hai creato in precedenza.

   5. Se vuoi, puoi modificare il nome del servizio, ad esempio impostandolo su my-service.

   6. Nell'elenco Regione, seleziona us-central1 (Iowa).

   7. In Autenticazione, seleziona Richiedi l'autenticazione.

   8. In Ingresso, seleziona Interno.

   9. Accetta tutti gli altri valori predefiniti.

   10. Fai clic su Crea e attendi il completamento del deployment.

Crea un bus Eventarc Advanced

Un bus riceve messaggi di eventi da un'origine messaggio o pubblicati da un fornitore e funge da router di messaggi.

Per ulteriori informazioni, consulta Creare un bus per instradare i messaggi.

Nota: puoi creare un solo bus per Google Cloud progetto.

1. Nella console Google Cloud, vai alla pagina Eventarc > Bus.

   Vai a Bus

2. Fai clic su Crea bus.

3. Nella pagina Crea un bus, segui questi passaggi:

   1. Inserisci un nome bus, ad esempio my-bus.
   2. Nell'elenco Regione, seleziona us-central1 (Iowa).

4. Accetta tutti gli altri valori predefiniti.

5. Fai clic su Crea.

Creare una registrazione Eventarc Advanced

Una registrazione determina quali messaggi vengono instradati a una destinazione e specifica anche la pipeline utilizzata per configurare una destinazione per i messaggi di evento.

Per ulteriori informazioni, consulta Creare una registrazione per ricevere eventi.

Quando utilizzi la console Google Cloud, puoi creare contemporaneamente una registrazione e una pipeline.

Nota: la creazione di una registrazione e di una pipeline potrebbe richiedere più di 10 minuti.

1. Per creare una registrazione, nella console Google Cloud vai alla pagina Eventarc > Pipeline.

   Vai a Pipeline

2. Fai clic su Crea pipeline.

3. Nel riquadro Dettagli pipeline, segui questi passaggi:

   1. Inserisci un nome per la pipeline, ad esempio my-pipeline.
   2. Nell'elenco Regione, seleziona us-central1 (Iowa). La pipeline deve essere creata nella stessa regione del bus.
   3. Accetta tutti gli altri valori predefiniti.
   4. Fai clic su Continua.

4. Nel riquadro Iscrizioni, segui questi passaggi:

   1. Fai clic su Aggiungi una registrazione.
   2. Inserisci un nome registrazione, ad esempio my-enrollment.
   3. Nell'elenco Bus Eventarc Advanced, seleziona il bus creato in precedenza.

   4. Nel campo Espressione CEL, scrivi un'espressione di valutazione utilizzando il linguaggio CEL. Ad esempio:

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

   5. Fai clic su Fine.

   6. Fai clic su Continua.

   7. Nel riquadro Mediazione eventi, fai di nuovo clic su Continua.

5. Nel riquadro Destinazione, segui questi passaggi:

   1. Nell'elenco Tipo di destinazione, seleziona Servizio Cloud Run (tramite HTTP) e poi il servizio Cloud Run che hai creato in precedenza.

   2. Nell'elenco Collegamento di rete, seleziona il collegamento di rete creato in precedenza.

   3. Seleziona la casella di controllo Attiva autenticazione.

      1. Nell'elenco Intestazione di autenticazione, seleziona Token OIDC.

      2. Nell'elenco Account di servizio, seleziona l'account di servizio che hai creato in precedenza e che chiamerà il servizio di destinazione. Questo indirizzo email dell'account di servizio viene utilizzato per generare il token OIDC.

6. Fai clic su Crea.

Pubblicare un messaggio di evento sul bus

Per pubblicare direttamente un messaggio nel bus, puoi utilizzare il comando gcloud beta eventarc message-buses publish o inviare una richiesta all'API REST Eventarc Publishing. Per ulteriori informazioni, vedi Pubblicare direttamente gli eventi.

Il messaggio deve essere in un formato CloudEvents, ovvero una specifica per la descrizione dei dati sugli eventi in un modo comune. L'elemento data è il payload dell'evento. In questo campo può essere inserito qualsiasi JSON ben formato. Per saperne di più sugli attributi del contesto CloudEvents, consulta Formato evento.

Pubblica un evento nel bus Eventarc Advanced utilizzando l'interfaccia a riga di comando gcloud e un flag --event-data e altri attributi evento:

gcloud beta 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

In alternativa, pubblica un evento nel bus Eventarc Advanced come messaggio JSON utilizzando gcloud CLI e un flag --json-message:

gcloud beta 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"}}'

Dopo aver pubblicato un evento, dovresti ricevere il messaggio "Evento pubblicato correttamente".

Visualizzare i dati sugli eventi nei log di Cloud Run

Dopo aver pubblicato un evento nel bus Eventarc Advanced, puoi controllare i log del servizio Cloud Run per verificare che l'evento sia stato ricevuto come previsto.

1. Nella console Google Cloud, vai alla pagina Cloud Run.

   Vai a Cloud Run

2. Nella pagina Servizi, fai clic sul nome del servizio.

3. Fai clic sulla scheda Log.

4. Puoi filtrare le voci di log e restituire l'output. Ad esempio, puoi cercare hello-world-data.

5. Cerca una voce di log simile alla seguente:

   2025-02-27 08:36:44.350 EST [2025-02-27 13:36:44,352] INFO in server: Body: b'{"key": "hello-world-data"}'
   

   Nota: se non vedi una voce di log, attendi qualche minuto e riprova a eseguire la ricerca.

Hai creato un bus Eventarc Advanced e una registrazione, hai pubblicato un messaggio di evento sul bus e hai verificato il risultato previsto nei log del servizio di ricezione di eventi.

Esegui la pulizia

Al termine delle attività descritte in questa guida rapida, puoi evitare la fatturazione continua eliminando le risorse che hai creato:

1. Elimina una subnet VPC.

2. Elimina un collegamento di rete VPC.

3. Elimina un repository Artifact Registry.

4. Elimina un servizio Cloud Run.

5. Elimina le risorse Eventarc Advanced:

   1. Eliminare una registrazione.

   2. Eliminare una pipeline.

   3. Eliminare un bus.

In alternativa, puoi eliminare il progetto Google Cloud per evitare addebiti. L'eliminazione del progetto Google Cloud interrompe la fatturazione per tutte le risorse utilizzate all'interno del progetto.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini elimini anche tutto il lavoro svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, il riuso dei progetti può aiutarti a non superare i limiti di quota.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Passaggi successivi

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