Pubblica eventi in un job Cloud Run

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

  • Un bus funge da router centrale, ricevendo messaggi dalle origini eventi o pubblicati dai provider.

  • Una registrazione indirizza i messaggi ricevuti dal bus a una o più destinazioni tramite una pipeline di elaborazione.

In questa guida rapida:

  1. Esegui il deployment di un job Cloud Run dal codice sorgente.

  2. Crea un bus Eventarc Advanced.

  3. Crea una registrazione Eventarc Advanced.

  4. Pubblica un messaggio di evento nel bus.

  5. Verifica che il job Cloud Run sia stato eseguito correttamente.

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

  3. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  4. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

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

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

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Artifact Registry, Cloud Build, 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 artifactregistry.googleapis.com cloudbuild.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

  8. Install the Google Cloud CLI.

  9. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  10. Per inizializzare gcloud CLI, esegui questo comando: 

    gcloud init

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

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

  12. Verify that billing is enabled for your Google Cloud project.

  13. Enable the Artifact Registry, Cloud Build, 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 artifactregistry.googleapis.com cloudbuild.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com run.googleapis.com 

  14. Aggiorna i componenti di gcloud: 
    gcloud components update

  15. Accedi utilizzando il tuo account: 
    gcloud auth login

  16. Imposta la variabile di configurazione utilizzata in questa guida rapida: 
    REGION=REGION

    Sostituisci REGION con una località supportata per il bus, ad esempio us-central1.

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

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

    Autorizzazioni obbligatorie

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

    Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

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

  18. Per concedere a Eventarc Advanced le autorizzazioni necessarie per eseguire un job Cloud Run, chiedi all'amministratore di concedere il ruolo IAM Cloud Run Invoker (roles/run.invoker) sul tuo progettoGoogle Cloud a un account di servizio:
    1. Crea un account di servizio. A scopo di test, collegherai questo service account 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

    19. Esegui il deployment di un job Cloud Run dal codice sorgente

    Esegui il deployment di un job Cloud Run come destinazione eventi. A differenza di un servizio Cloud Run, che ascolta e gestisce le richieste, un job Cloud Run esegue solo le sue attività e termina quando ha finito. Un job non ascolta né gestisce le richieste.

    Sono supportate altre destinazioni di eventi, come un argomento Pub/Sub, Workflows o un altro endpoint HTTP. Per saperne di più, vedi Fornitori e destinazioni di eventi.

    Crea un job dal codice sorgente Python utilizzando il comando gcloud run jobs deploy. Il codice viene automaticamente pacchettizzato in un'immagine container, caricato su Artifact Registry e poi sottoposto a deployment su Cloud Run.

    1. Crea una directory denominata jobs e vai alla directory:

      mkdir jobs
cd jobs

    2. Crea un file main.py e copia al suo interno il seguente codice campione:

      import os

TASK_INDEX = os.getenv("CLOUD_RUN_TASK_INDEX", 0)

def main():
    """
    This job prints "Hello world"
    """
    print(f"Starting task #{TASK_INDEX}...")
    print("Hello world")
    print(f"Completed task #{TASK_INDEX}.")

# Start script
if __name__ == "__main__":
    main()

    3. Crea un file di testo denominato Procfile senza estensione e copia il seguente testo al suo interno:

      web: python3 main.py

    4. Esegui il deployment del job:

      gcloud run jobs deploy JOB_NAME \
    --source . \
    --tasks 1 \
    --region=$REGION

      Sostituisci JOB_NAME con un nome univoco per il job Cloud Run, ad esempio my-job.

    Crea un bus Eventarc Advanced

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

    Per maggiori informazioni, vedi Creare un bus per indirizzare i messaggi.

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

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

    Sostituisci BUS_NAME con l'ID del bus o un nome completo, ad esempio my-bus.

    Crea una registrazione Eventarc Advanced

    Una registrazione determina quali messaggi vengono instradati a una destinazione. Specifica anche la pipeline utilizzata per configurare la destinazione dei messaggi evento. In questo caso, la destinazione di destinazione è un job Cloud Run.

    Per saperne di più, consulta Creare una registrazione per ricevere eventi.

    Quando utilizzi gcloud CLI, prima crei una pipeline, poi crei una registrazione:

    1. Crea una pipeline utilizzando il 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

      Sostituisci quanto segue:

      • PIPELINE_NAME: l'ID della pipeline o un nome completo, ad esempio my-pipeline.
      • PROJECT_NUMBER: il tuo numero di progetto Google Cloud . Puoi recuperare il numero di progetto eseguendo questo comando:
      gcloud projects describe PROJECT_ID --format='value(projectNumber)'

      Tieni presente quanto segue:

      • La chiave http_endpoint_message_binding_template trasforma l'evento nel formato previsto dall'API Cloud Run Admin. Quando definisci un binding del messaggio, devi configurare un formato di input per accedere al payload.
      • La chiave oauth_token_authentication_service_account specifica un indirizzo email del service account. Questo indirizzo email viene utilizzato per generare un token OAuth in genere utilizzato solo quando si chiamano le API di Google ospitate su *.googleapis.com.

    2. Crea una registrazione utilizzando il 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

      Sostituisci quanto segue:

      • ENROLLMENT_NAME: l'ID della registrazione o un nome completo, ad esempio my-enrollment.

      • MATCH_EXPRESSION: l'espressione di corrispondenza per questa registrazione utilizzando CEL, ad esempio:

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

    Pubblica un messaggio di evento nel bus

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

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

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

    Esempio 1

    Pubblica un evento in un bus utilizzando gcloud CLI e un --event-data e altri flag di attributo dell'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

    Esempio 2

    Pubblica un evento in un bus come messaggio JSON utilizzando gcloud CLI e un flag --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"}}'

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

    Conferma che il job Cloud Run sia stato eseguito correttamente

    Dopo aver pubblicato un evento nel bus Eventarc Advanced, controlla i log del job Cloud Run per verificare che il job Cloud Run sia stato eseguito correttamente e che sia stato stampato "Hello world". Potrebbero essere necessari alcuni minuti prima che il job venga eseguito e completato.

    1. Filtra le voci di log e restituisci l'output utilizzando il comando gcloud logging read:

      gcloud logging read 'textPayload: "Hello world"'

    2. Cerca una voce di log simile alla seguente:

      insertId: 693c8dd0000cb2976d7966b8
...
labels:
    job_name: JOB_NAME
    location: REGION
    project_id: PROJECT_ID
type: cloud_run_job
textPayload: Hello world
timestamp: '2025-12-12T21:49:04.832151Z'

    3. Puoi anche verificare che il job Cloud Run sia stato eseguito correttamente utilizzando il comando gcloud run jobs describe:

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

      Dovresti ricevere un output simile al seguente:

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

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

    Esegui la pulizia

    Per evitare l'addebito di ulteriori costi dopo aver completato questa guida rapida, elimina le risorse che hai creato:

    1. Elimina un job Cloud Run.

    2. Elimina le risorse Eventarc Advanced:

      1. Eliminare una registrazione.

      2. Eliminare una pipeline.

      3. Eliminare un bus.

    In alternativa, elimina il progetto Google Cloud per evitare addebiti. L'eliminazione del progetto Google Cloud interrompe la fatturazione per tutte le risorse utilizzate al suo interno.

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

    Passaggi successivi