Pubblicare e ricevere eventi creando un bus e una registrazione

Pubblicare e ricevere eventi creando un bus e una registrazione

Avanzate

Anteprima - Eventarc Advanced

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

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 eventi da un'origine messaggio o pubblicati da un provider 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. Eseguire il deployment di un servizio di ricezione di eventi in Cloud Run.

4. Crea un bus Eventarc Advanced.

5. Crea una registrazione Eventarc Advanced.

6. Pubblica un messaggio di evento sul bus.

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

Puoi completare questa guida rapida utilizzando Google Cloud 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 Google Cloud ambiente 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. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select 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.

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

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

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

   gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

7. Install the Google Cloud CLI.

8. To initialize the gcloud CLI, run the following command:

   gcloud init

9. Create or select 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.

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

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

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

    gcloud services enable artifactregistry.googleapis.com cloudbuild.googleapis.com compute.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com

12. Aggiorna i componenti gcloud:

    gcloud components update

13. Accedi utilizzando il tuo account:

    gcloud auth login

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

    REGION=REGION

    Sostituisci REGION con una posizione supportata per il bus.

15. Se sei il creator del progetto, ti viene assegnato il ruolo di proprietario di base (roles/owner). Per impostazione predefinita, questo ruolo Identity and Access Management (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 saperne di più 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.

16. Concedi i seguenti ruoli sul progetto all'account di servizio predefinito di Compute Engine. Questi ruoli sono necessari per creare ed eseguire il deployment dell'immagine container:
    • 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

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/artifactregistry.writer
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/logging.logWriter
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/storage.objectUser

    Sostituisci PROJECT_NUMBER con il numero Google Cloud del tuo progetto. Puoi trovare il numero del progetto nella pagina Welcome della console Google Cloud o eseguendo il seguente comando:

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

17. Per impostazione predefinita, solo i proprietari del progetto, gli editor del progetto e gli amministratori e gli invocatori di Cloud Run possono chiamare i servizi Cloud Run. Per configurare l'autenticazione, concedi il ruolo invocatore Cloud Run (run.invoker) nel Google Cloud tuo progetto a un account di servizio:
    1. Crea un account di servizio. A scopo di test, collegherai questo account di servizio a una pipeline Eventarc Advanced per rappresentare l'identità della pipeline.

       gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

       Sostituisci SERVICE_ACCOUNT_NAME con un nome per il tuo account di servizio.
    2. Concedi il ruolo IAM roles/run.invoker all'account di servizio:

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

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

    • Concedi l'autorizzazione a selezionare account di servizio o gruppi 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 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 utilizza il flag --enable-private-ip-google-access per attivare l'accesso privato Google:

gcloud compute networks subnets create SUBNET_NAME \
    --network=default \
    --range=10.8.0.0/24 \
    --region=$REGION \
    --enable-private-ip-google-access

Sostituisci SUBNET_NAME con il nome della subnet, ad esempio my-subnet.

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:

gcloud compute network-attachments create ATTACHMENT_NAME \
   --region=$REGION \
   --connection-preference=ACCEPT_AUTOMATIC \
   --subnets=SUBNET_NAME

Sostituisci ATTACHMENT_NAME con il nome dell'attacco alla rete, ad esempio my-network-attachment.

Creare un repository standard Artifact Registry

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

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

Sostituisci REPOSITORY con un nome univoco per il repository Artifact Registry, ad esempio my-repo.

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

Esegui il deployment di un servizio Cloud Run che registra 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. 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

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

   gcloud run deploy SERVICE_NAME \
       --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
       --platform managed \
       --ingress internal \
       --no-allow-unauthenticated \
       --region=$REGION

   Sostituisci SERVICE_NAME con il nome del servizio, ad esempio my-service.

Quando viene visualizzato l'URL del servizio Cloud Run, il deployment è completato. Prendi nota di questo URL per utilizzarlo in un passaggio successivo.

Crea un bus Eventarc Advanced

Crea un bus Eventarc Advanced nel tuo progetto utilizzando il comando gcloud beta eventarc message-buses create:

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

Sostituisci BUS_NAME con l'ID o l'identificatore completamente qualificato del tuo bus, ad esempio my-bus.

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

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

Creare una registrazione Eventarc Advanced

Una registrazione determina quali messaggi vengono instradati a una destinazione. Inoltre, specifica la pipeline attraverso la quale devono essere instradati i messaggi. La pipeline viene utilizzata per configurare una destinazione per i messaggi evento.

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

Quando utilizzi gcloud CLI, devi prima creare una pipeline e poi una registrazione.

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

1. Crea una pipeline utilizzando il comando gcloud beta eventarc pipelines create:

   gcloud beta eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',network_attachment=ATTACHMENT_NAME,google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --location=$REGION

   Sostituisci quanto segue:

   • PIPELINE_NAME: l'ID della pipeline o un nome completamente qualificato.
   • CLOUD_RUN_SERVICE_URL: l'URL completo del servizio Cloud Run, ad esempio https://SERVICE_NAME-abcdef-uc.a.run.app. Si tratta della destinazione per i messaggi relativi agli eventi.

   Tieni presente che la chiave google_oidc_authentication_service_account specifica un'email dell'account di servizio utilizzata per generare un token OIDC.

2. Crea una registrazione utilizzando il comando gcloud beta eventarc enrollments create:

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

   Sostituisci quanto segue:

   • ENROLLMENT_NAME: l'ID della registrazione o un nome completamente qualificato.
   • MATCH_EXPRESSION: l'espressione di corrispondenza per questa registrazione utilizzando CEL, ad esempio "message.type == 'hello-world-type'".

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

Di seguito sono riportati alcuni esempi di pubblicazione diretta di un evento in un bus Eventarc Advanced:

Esempio 1

Puoi pubblicare un evento in un bus utilizzando l'interfaccia a riga di comando gcloud e un --event-data e altri flag degli 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

Esempio 2

Puoi pubblicare un evento in un bus 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. Filtra le voci di log e restituisce l'output utilizzando il comando gcloud logging read:

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

2. Cerca una voce di log simile alla seguente:

   insertId: 670808e70002b5c6477709ae
   labels:
   instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
   logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
   receiveTimestamp: '2024-10-10T17:03:35.424659450Z'
   resource:
   labels:
   ...
   type: cloud_run_revision
   textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
     }'"
   timestamp: '2024-10-10T17:03:35.177606Z'
   

   Nota: se non vedi una voce di log, attendi qualche minuto e riprova con il comando gcloud logging read.

Hai creato correttamente 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. Elimina 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.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Passaggi successivi

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