Pubblica eventi in una tabella BigQuery

Pubblica eventi in una tabella BigQuery

Avanzate

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 ti consente di centralizzare il flusso di messaggi nel sistema e funge da router. Riceve messaggi di eventi da un'origine messaggi o pubblicati da un provider e li valuta in base a una registrazione.

• Una registrazione identifica un abbonamento a un particolare 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 tabella BigQuery.

2. Crea un bus Eventarc Advanced.

3. Crea una registrazione Eventarc Advanced.

4. Pubblica un messaggio di evento nel bus.

5. Visualizza i dati degli eventi nella tabella BigQuery.

Puoi completare questa guida rapida utilizzando gcloud CLI e lo strumento a riga di comando bq.

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.

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.

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

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

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.

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Eventarc APIs:

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com

Install the Google Cloud CLI.

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

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

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.

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and Eventarc APIs:

gcloud services enable bigquery.googleapis.com eventarc.googleapis.com eventarcpublishing.googleapis.com

1. Aggiorna i componenti di gcloud:

   gcloud components update

2. Accedi utilizzando il tuo account:

   gcloud auth login

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

4. 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:

   • Editor dati BigQuery (roles/bigquery.dataEditor)
   • Sviluppatore Eventarc (roles/eventarc.developer)
   • Eventarc Message Bus Admin (roles/eventarc.messageBusAdmin)
   • Logs View Accessor (roles/logging.viewAccessor)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Amministratore account di servizio (roles/iam.serviceAccountAdmin)
   • Utente service account (roles/iam.serviceAccountUser)
   • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

   Per ulteriori informazioni 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.

5. Per concedere a Eventarc Advanced le autorizzazioni necessarie per aggiornare le proprietà della tabella BigQuery, chiedi all'amministratore di concedere il ruolo IAM Editor dati BigQuery (roles/bigquery.dataEditor) sul tuo progetto Google 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/bigquery.dataEditor al account di servizio:

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

Crea una tabella BigQuery

Crea una tabella BigQuery come destinazione eventi. Sono supportate altre destinazioni eventi, ad esempio un argomento Pub/Sub, Workflows o un altro endpoint HTTP. Per ulteriori informazioni, vedi Fornitori e destinazioni di eventi.

Prima di creare una tabella BigQuery, crea un set di dati che funge da contenitore di primo livello per la tabella e uno schema della tabella.

1. Per creare un nuovo set di dati, utilizza il comando bq mk con il flag --dataset.

   bq --location=$REGION mk --dataset DATASET_ID

   Sostituisci DATASET_ID con un nome univoco per il set di dati BigQuery, ad esempio my_dataset.

2. Nel terminale, crea un nuovo file denominato my-schema.json.

3. Copia e incolla lo schema seguente nel nuovo file, quindi salva il file.

   [
       {
           "name": "name",
           "type": "STRING",
           "mode": "REQUIRED"
       },
       {
           "name": "age",
           "type": "INTEGER",
           "mode": "NULLABLE"
       }
   ]

4. Per creare una tabella, utilizza il comando bq mk con il flag --table.

   bq mk --table PROJECT_ID:DATASET_ID.TABLE_ID my-schema.json

   Sostituisci TABLE_ID con un nome univoco per la tabella BigQuery, ad esempio my-table.

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 saperne di più, consulta Creare un bus per instradare i messaggi.

Nota: puoi creare un bus per Google Cloud progetto per regione supportata.

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 e specifica anche la pipeline utilizzata per configurare una destinazione per i messaggi di evento. In questo caso, la destinazione è un endpoint API BigQuery.

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

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

Quando utilizzi gcloud CLI, prima crei una pipeline e 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://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID/insertAll',http_endpoint_message_binding_template='{"headers": headers.merge({"content-type":"application/json"}), "body": {"rows":[{"json":message.data}]}}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   Sostituisci PIPELINE_NAME con l'ID della pipeline o un nome completo, ad esempio my-pipeline.

   Tieni presente quanto segue:

   • Il tasto http_endpoint_message_binding_template trasforma l'evento nel formato previsto dall'API. 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. Questa email viene utilizzata per generare un token OAuth che in genere deve essere utilizzato solo quando si chiamano le API di Google ospitate su *.googleapis.com.
   • Il flag input-payload-format-json specifica che il formato del payload di input della pipeline è JSON. Tutti i messaggi che non corrispondono a questo formato vengono trattati come errori permanenti.

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, puoi utilizzare il comando gcloud eventarc message-buses publish o inviare 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 degli eventi in modo comune. L'elemento data è il payload del tuo evento e deve corrispondere allo schema della tua tabella BigQuery. In questo campo può essere inserito qualsiasi JSON ben formato. Per saperne di più sugli attributi di contesto di CloudEvents, consulta Formato dell'evento.

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

Esempio 1

Puoi pubblicare un evento in un bus utilizzando gcloud CLI e un --event-data e altri flag di attributo evento:

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"name": "my-name", "age": "20"}' \
    --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 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":
 {"name": "my-name", "age": "20"}}'

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

Visualizzare i dati degli eventi nella tabella BigQuery

Dopo aver pubblicato un evento nel bus Eventarc Advanced, puoi utilizzare il comando bq query per verificare che sia stata aggiunta una nuova riga alla tabella BigQuery.

bq query \
    --use_legacy_sql=false \
    'SELECT
      *
    FROM
      `PROJECT_ID.DATASET_ID.TABLE_ID`
    LIMIT
      10;'

Hai creato correttamente un bus Eventarc Advanced e una registrazione, hai pubblicato un messaggio di evento nel bus e hai verificato il risultato previsto eseguendo una query sulla tabella BigQuery.

Esegui la pulizia

Al termine delle attività descritte in questa guida rapida, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato:

1. Eliminare una tabella BigQuery.

2. Elimina un set di dati BigQuery.

3. Elimina le risorse Eventarc Advanced:

   1. Eliminare una registrazione.

   2. Eliminare una pipeline.

   3. Elimina un bus.

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

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 che hai 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, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Passaggi successivi

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