Questo documento descrive come creare una sottoscrizione BigQuery. Puoi utilizzare la console Google Cloud, Google Cloud CLI, la libreria client oppure l'API Pub/Sub per creare una sottoscrizione BigQuery.
Prima di iniziare
Prima di leggere questo documento, assicurati di acquisire familiarità con quanto segue:
Come funzionano gli abbonamenti.
Il flusso di lavoro per le sottoscrizioni BigQuery.
Come configurare un argomento messaggi non recapitabili per gestire gli errori dei messaggi.
Oltre alla tua familiarità con Pub/Sub e BigQuery, assicurati di soddisfare i seguenti prerequisiti Prima di creare una sottoscrizione BigQuery:
Esiste una tabella BigQuery. In alternativa, puoi crearne uno quando crei la sottoscrizione BigQuery come descritto in nelle sezioni successive di questo documento.
Compatibilità tra lo schema dell'argomento Pub/Sub e la tabella BigQuery. Se aggiungi un modello non compatibile Nella tabella BigQuery viene visualizzato un errore relativo alla compatibilità . Per ulteriori informazioni, vedi Compatibilità dello schema.
Ruoli e autorizzazioni richiesti
Di seguito è riportato un elenco di linee guida relative a ruoli e autorizzazioni:
Per creare una sottoscrizione, devi configurare il controllo dell'accesso a livello di progetto livello.
Sono necessarie anche le autorizzazioni a livello di risorsa sottoscrizioni e argomenti si trovano in progetti diversi, come illustrato più avanti. in questa sezione.
Per creare una sottoscrizione BigQuery, L'account di servizio Pub/Sub deve disporre dell'autorizzazione per scrivere una specifica tabella BigQuery. Per ulteriori informazioni su come concedi queste autorizzazioni, consulta la sezione successiva di questo documento.
Puoi configurare una sottoscrizione BigQuery in un progetto scrivere in una tabella BigQuery di un altro progetto.
Per ottenere le autorizzazioni necessarie per creare sottoscrizioni BigQuery,
chiedi all'amministratore di concederti
Ruolo IAM dell'editor Pub/Sub (roles/pubsub.editor
) nel progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Questo ruolo predefinito contiene le autorizzazioni necessarie per creare sottoscrizioni BigQuery. Per vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
Per creare sottoscrizioni BigQuery sono necessarie le seguenti autorizzazioni:
-
Esegui il pull da una sottoscrizione:
pubsub.subscriptions.consume
-
Creare una sottoscrizione:
pubsub.subscriptions.create
-
Eliminare una sottoscrizione:
pubsub.subscriptions.delete
-
Acquistare un abbonamento:
pubsub.subscriptions.get
-
Crea una sottoscrizione:
pubsub.subscriptions.list
-
Aggiornare un abbonamento:
pubsub.subscriptions.update
-
Collegare una sottoscrizione a un argomento:
pubsub.topics.attachSubscription
-
Ottieni il criterio IAM per una sottoscrizione:
pubsub.subscriptions.getIamPolicy
-
Configura il criterio IAM per un abbonamento:
pubsub.subscriptions.setIamPolicy
Potresti anche riuscire a ottenere queste autorizzazioni con ruoli personalizzati e altri ruoli predefiniti.
Se hai bisogno di creare BigQuery
sottoscrizioni in un progetto associate a un argomento in un altro
chiedi all'amministratore dell'argomento di concederti anche l'editor Pub/Sub
(roles/pubsub.editor)
nell'argomento.
Assegnare ruoli BigQuery all'account di servizio Pub/Sub
Alcuni servizi Google Cloud hanno account di servizio gestiti da Google Cloud che consentono
per accedere alle tue risorse. Questi account di servizio
noti come agenti di servizio. Pub/Sub crea e gestisce
per ogni progetto nel formato
service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
.
Per creare una sottoscrizione BigQuery, il comando Pub/Sub l'account di servizio deve disporre dell'autorizzazione per scrivere alla tabella BigQuery specifica e leggere i metadati della tabella.
Concedi l'editor dati BigQuery (roles/bigquery.dataEditor
)
all'account di servizio Pub/Sub.
Nella console Google Cloud, vai alla pagina IAM.
Fai clic su Concedi accesso.
Nella sezione Aggiungi entità, inserisci il nome del tuo Pub/Sub l'account di servizio. Il formato dell'account di servizio è
service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
. Ad esempio, per un progetto conproject-number=112233445566
, l'account di servizio è nel formatoservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
.Nella sezione Assegna ruoli, fai clic su Aggiungi un altro ruolo.
Nel menu a discesa Seleziona un ruolo, inserisci
BigQuery
. e seleziona il ruolo Editor dati BigQuery.Fai clic su Salva.
Per saperne di più su IAM di BigQuery, consulta Ruoli e autorizzazioni di BigQuery.
Proprietà delle sottoscrizioni BigQuery
Quando configuri una sottoscrizione BigQuery, puoi specificare quanto segue proprietà.
Proprietà comuni
Scopri di più sulle proprietà di abbonamento comuni che puoi impostare per tutte le sottoscrizioni.
Utilizza schema argomento
Questa opzione consente a Pub/Sub di utilizzare lo schema dell'argomento Pub/Sub a cui è allegato. Inoltre, Pub/Sub scrive i campi dei messaggi nella casella colonne nella tabella BigQuery.
Quando utilizzi questa opzione, ricordati di controllare i seguenti requisiti aggiuntivi:
I campi dello schema dell'argomento e dello schema BigQuery devono avere gli stessi nomi e i tipi devono essere compatibili tra loro.
Anche qualsiasi campo facoltativo nello schema dell'argomento deve essere sono facoltative nello schema BigQuery.
I campi obbligatori nello schema dell'argomento non devono essere necessariamente richiesta nello schema BigQuery.
Se sono presenti campi BigQuery non presenti in lo schema dell'argomento, questi campi BigQuery deve essere in modalità
NULLABLE
.Se lo schema dell'argomento ha campi aggiuntivi che non sono presenti nello schema BigQuery e questi ultimi seleziona l'opzione Rilascia campi sconosciuti.
Puoi selezionare solo una delle proprietà della sottoscrizione, Utilizza schema argomento. o Utilizza schema della tabella.
Se non selezioni l'opzione Utilizza schema argomento o Utilizza schema della tabella,
assicurati che la tabella BigQuery abbia una colonna denominata data
di
digita BYTES
, STRING
o JSON
. Pub/Sub scrive il messaggio
colonna BigQuery.
Potresti non vedere le modifiche allo schema degli argomenti Pub/Sub o Lo schema della tabella BigQuery viene applicato immediatamente con i messaggi vengono scritte nella tabella BigQuery. Ad esempio, se il campo Drop campi sconosciuti è abilitata ed è presente un campo nella dello schema Pub/Sub, ma non di BigQuery, i messaggi scritti nella tabella BigQuery potrebbero non contenere il campo dopo averlo aggiunto allo schema di BigQuery. In seguito, gli schemi sincronizzati e i messaggi successivi includono il campo.
Quando utilizzi l'opzione Utilizza schema argomento per BigQuery di abbonamento, puoi anche sfruttare la modifica acquisizione dei dati (CDC). CDC aggiorna le tabelle BigQuery l'elaborazione e l'applicazione di modifiche alle righe esistenti.
Per saperne di più su questa funzionalità, consulta Flusso di aggiornamenti delle tabelle con Change Data Capture (CDC).
Per scoprire come utilizzare questa funzionalità con le sottoscrizioni BigQuery, consulta Change Data Capture (CDC) di BigQuery.
Utilizza schema tabella
Questa opzione consente a Pub/Sub di utilizzare lo schema Tabella BigQuery per scrivere i campi di un file JSON nelle colonne corrispondenti. Quando utilizzi questa opzione, ricordati di verifica i seguenti requisiti aggiuntivi:
I messaggi pubblicati devono essere in formato JSON.
Se l'argomento della sottoscrizione ha uno schema associato, la proprietà di codifica dei messaggi deve essere impostata su
JSON
.Se sono presenti campi BigQuery non presenti in i messaggi, questi campi di BigQuery devono essere in modalità
NULLABLE
.Se i messaggi contengono campi aggiuntivi che non sono presenti Schema BigQuery e questi campi possono essere eliminati, seleziona il opzione Trascina campi sconosciuti.
Nel messaggio JSON, valori
DATE
,DATETIME
,TIME
eTIMESTAMP
devono essere numeri interi che rispettano le rappresentazioni supportate.Nel messaggio JSON, i valori
NUMERIC
eBIGNUMERIC
devono essere codificati in byte utilizzando BigDecimalByteStringEncoder.Puoi selezionare solo una delle proprietà della sottoscrizione, Utilizza schema argomento. o Utilizza schema della tabella.
Se non selezioni l'opzione Utilizza schema argomento o Utilizza schema della tabella,
assicurati che la tabella BigQuery abbia una colonna denominata data
di
digita BYTES
, STRING
o JSON
. Pub/Sub scrive il messaggio
colonna BigQuery.
Potresti non vedere le modifiche allo schema della tabella BigQuery ha effetto immediato con i messaggi scritti nella tabella BigQuery. Ad esempio, se l'opzione Rilascia campi sconosciuti è abilitata e un campo viene dei messaggi, ma non dello schema BigQuery. i messaggi scritti nella tabella BigQuery potrebbero non contenere il campo dopo averlo aggiunto allo schema di BigQuery. In seguito, lo schema si sincronizza e i messaggi successivi includono il campo.
Quando utilizzi l'opzione Utilizza schema della tabella per la tua sottoscrizione BigQuery, puoi possono anche sfruttare la tecnologia Change Data Capture (CDC) di BigQuery. CDC aggiorna le tabelle BigQuery elaborando e applicando modifiche alle righe.
Per saperne di più su questa funzionalità, consulta Flusso di aggiornamenti delle tabelle con Change Data Capture (CDC).
Per informazioni su come utilizzare questa funzionalità con le sottoscrizioni BigQuery, consulta Acquisizione dei dati sulle modifiche a BigQuery.
Rilascia campi sconosciuti
Questa opzione viene utilizzata con Utilizza schema argomento o Utilizza schema tabella. . Questa opzione consente a Pub/Sub di eliminare qualsiasi campo presente nell'argomento. nello schema o nel messaggio, ma non nello schema BigQuery. Senza Drop sconosciuto campi impostati, i messaggi con campi aggiuntivi non vengono scritti in in BigQuery e rimangono nel backlog della sottoscrizione. La termina con uno stato di errore.
Scrivi metadati
Questa opzione consente a Pub/Sub scrivere i metadati di ciascun messaggio in colonne aggiuntive Tabella BigQuery. In caso contrario, i metadati non viene scritto nella tabella BigQuery.
Se selezioni l'opzione Scrivi metadati, assicurati che il valore La tabella BigQuery contiene i campi descritti nella seguente tabella.
Se non selezioni l'opzione Scrivi metadati, la tabella BigQuery di destinazione richiede solo il campo data
, a meno che
use_topic_schema
è vero. Se selezioni sia Scrivi metadati che
Utilizza lo schema dell'argomento; lo schema dell'argomento deve essere
Non devono contenere campi con nomi corrispondenti a quelli dei parametri dei metadati.
Questa limitazione include le versioni camelcase di questi parametri snake case.
Parametri | |
---|---|
subscription_name |
STRINGA Nome di una sottoscrizione. |
message_id |
STRINGA ID di un messaggio |
publish_time |
TIMESTAMP L'ora di pubblicazione di un messaggio. |
data |
BYTES, STRING o JSON Il corpo del messaggio. Il campo |
attributes |
STRING o JSON Un oggetto JSON contenente tutti gli attributi dei messaggi. Inoltre, contiene altri campi che fanno parte il messaggio Pub/Sub, inclusa la chiave di ordinamento, se presente. |
Creare una sottoscrizione BigQuery
Gli esempi riportati di seguito mostrano come creare una sottoscrizione con la distribuzione BigQuery.
Console
- Nella console Google Cloud, vai alla pagina Abbonamenti.
- Fai clic su Crea sottoscrizione.
- Inserisci un nome nel campo Subscription ID (ID abbonamento).
Per informazioni su come assegnare un nome a una sottoscrizione, vedi Linee guida per assegnare un nome un argomento o una sottoscrizione.
- Scegli o crea un argomento dal menu a discesa. L'abbonamento riceve messaggi dall'argomento.
- Seleziona Tipo di recapito come Scrivi in BigQuery.
- Seleziona il progetto per la tabella BigQuery.
- Seleziona un set di dati esistente o creane uno nuovo.
Per informazioni su come creare un set di dati, consulta Creazione di set di dati.
- Seleziona una tabella esistente o creane una nuova.
Per informazioni su su come creare una tabella, consulta Creazione di tabelle.
- Ti consigliamo vivamente di attivare Dead
per gestire gli errori dei messaggi.
Per ulteriori informazioni, vedi Dead all'argomento delle lettere.
- Fai clic su Crea.
Puoi creare una sottoscrizione anche dalla pagina Argomenti. Questa scorciatoia è utile per associare gli argomenti alle sottoscrizioni.
- Nella console Google Cloud, vai a Topics. .
- Fai clic sulla more_vert accanto all'argomento che ti interessa per creare una sottoscrizione.
- Dal menu contestuale, seleziona Crea abbonamento.
- Seleziona Tipo di recapito come Scrivi in BigQuery.
- Seleziona il progetto per la tabella BigQuery.
- Seleziona un set di dati esistente o creane uno nuovo.
Per informazioni su come creare un set di dati, consulta Creazione di set di dati.
- Seleziona una tabella esistente o creane una nuova.
Per informazioni su su come creare un set di dati, consulta Creazione di tabelle.
- Ti consigliamo vivamente di attivare Dead
per gestire gli errori dei messaggi.
Per ulteriori informazioni, vedi Dead all'argomento delle lettere.
- Fai clic su Crea.
gcloud
-
Nella console Google Cloud, attiva Cloud Shell.
Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.
-
Per creare un abbonamento Pub/Sub, utilizza
gcloud pubsub subscriptions create
:gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --bigquery-table=PROJECT_ID:DATASET_ID.TABLE_ID
Sostituisci quanto segue:
- SUBSCRIPTION_ID: specifica l'ID del abbonamento.
- TOPIC_ID: specifica l'ID dell'argomento. La richiede uno schema.
- PROJECT_ID: specifica l'ID del progetto.
- DATASET_ID: specifica l'ID di un elemento esistente del set di dati. Per creare un set di dati, consulta Creare set di dati.
- TABLE_ID: specifica l'ID di una tabella esistente. La tabella richiede un campo data se l'argomento non ha uno schema. Per creare una tabella, consulta Creare una tabella. una tabella vuota con una definizione di schema.
C++
Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub C++ documentazione di riferimento.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
C#
Prima di provare questo esempio, segui le istruzioni per la configurazione di C# nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub C# documentazione di riferimento.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Go
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub Go documentazione di riferimento.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub Java documentazione di riferimento.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Node.js
Node.js
PHP
Prima di provare questo esempio, segui le istruzioni per la configurazione di PHP nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub PHP documentazione di riferimento.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub Python documentazione di riferimento.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Ruby
Prima di provare questo esempio, segui le istruzioni per la configurazione di Ruby nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub Ruby documentazione di riferimento.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Passaggi successivi
- Crea o modifica una sottoscrizione con i comandi
gcloud
. - Crea o modifica un abbonamento con le API REST.
- Risolvi i problemi relativi a un abbonamento BigQuery.