Creare sottoscrizioni BigQuery

Questo documento descrive come creare un abbonamento BigQuery. Puoi utilizzare la console Google Cloud , Google Cloud CLI, la libreria client o l'API Pub/Sub per creare una sottoscrizione BigQuery.

Prima di iniziare

Prima di leggere questo documento, assicurati di conoscere quanto segue:

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 l'abbonamento BigQuery, come descritto nelle sezioni successive di questo documento.

  • Compatibilità tra lo schema dell'argomento Pub/Sub e la tabella BigQuery. Se aggiungi una tabella BigQuery non compatibile, riceverai un messaggio di errore relativo alla compatibilità. Per saperne di più, consulta la sezione Compatibilità dello schema.

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per creare una sottoscrizione BigQuery, chiedi all'amministratore di concederti il ruolo IAM Pub/Sub Editor (roles/pubsub.editor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per creare un abbonamento BigQuery. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare un abbonamento BigQuery sono necessarie le seguenti autorizzazioni:

  • pubsub.subscriptions.create sul progetto
  • pubsub.topics.attachSubscription sull'argomento

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Abbonamenti tra progetti

Se crei una sottoscrizione in un progetto per un argomento in un altro progetto, devi disporre dell'autorizzazione pubsub.subscriptions.create sul progetto in cui stai creando la sottoscrizione e dell'autorizzazione pubsub.topics.attachSubscription sull'argomento.

Concedi ruoli IAM al account di servizio

Pub/Sub utilizza un account di servizio Identity and Access Management (IAM) per accedere alle risorse Google Cloud . Per impostazione predefinita, utilizza il service agent Pub/Sub (service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com).

Per consentire a Pub/Sub di scrivere in una tabella BigQuery, il account di servizio richiede il ruolo Editor dati BigQuery (roles/bigquery.dataEditor). Puoi concedere le autorizzazioni al account di servizio per il progetto o la tabella, nel seguente modo:

Progetto

  1. Nella console Google Cloud vai alla pagina IAM.

    Vai a IAM

  2. Seleziona Includi concessioni di ruoli fornite da Google.

  3. Trova la riga del account di servizio Cloud Pub/Sub e fai clic su Modifica entità.

  4. Fai clic su Aggiungi un altro ruolo e seleziona il ruolo Editor dati BigQuery.

Per maggiori informazioni, consulta Concedi un ruolo IAM utilizzando la console.

Tabella

  1. Nella console Google Cloud , vai a BigQuery Studio.

    Vai a BigQuery Studio

  2. Nella casella di ricerca del riquadro Explorer con l'etichetta Filtra per nome ed etichette, digita il nome della tabella e premi Invio.

  3. Nei risultati di ricerca, fai clic sul nome della tabella a cui vuoi concedere l'autorizzazione.

  4. Nella scheda Dettagli, fai clic su Condividi > Gestisci autorizzazioni.

  5. Fai clic su Aggiungi entità, quindi inserisci l'identificatore del account di servizio nel seguente formato:

    service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com.

  6. Nell'elenco Assegna ruoli, seleziona BigQuery Data Editor.

  7. Fai clic su Salva. All'entità viene concesso il ruolo sulla risorsa.

Utilizzare un account di servizio personalizzato

Se concedi il ruolo Editor dati BigQuery all'account di servizio Cloud Pub/Sub, qualsiasi utente che dispone dell'autorizzazione per creare un abbonamento nel tuo progetto può scrivere nella tabella BigQuery. Se vuoi fornire autorizzazioni più granulari, configura un service account gestito dall'utente.

Per configurare un service account gestito dall'utente per scrivere in BigQuery sono necessarie le seguenti autorizzazioni:

  • Il account di servizio gestito dall'utente deve avere il ruolo Editor dati BigQuery.

  • Il account di servizio Cloud Pub/Sub deve disporre dell'autorizzazione iam.serviceAccounts.getAccessToken sul service account gestito dall'utente.

  • L'utente che crea l'abbonamento deve disporre dell'autorizzazione iam.serviceAccounts.actAs sul account di servizio gestito dall'utente.

Quando crei l'abbonamento, specifica il account di servizio gestito dall'utente come service account di abbonamento.

Proprietà delle sottoscrizioni BigQuery

Le sottoscrizioni BigQuery supportano tutte le proprietà di sottoscrizione comuni. Le sezioni seguenti descrivono le proprietà specifiche degli abbonamenti BigQuery.

Utilizza schema argomento

Questa opzione consente a Pub/Sub di utilizzare lo schema dell'argomento Pub/Sub a cui è collegata la sottoscrizione. Inoltre, Pub/Sub scrive i campi nei messaggi nelle colonne corrispondenti della tabella BigQuery.

Quando utilizzi questa opzione, ricorda di controllare i seguenti requisiti aggiuntivi:

  • I campi nello schema dell'argomento e nello schema BigQuery devono avere gli stessi nomi e i loro tipi devono essere compatibili tra loro.

  • Qualsiasi campo facoltativo nello schema dell'argomento deve essere facoltativo anche nello schema BigQuery.

  • I campi obbligatori nello schema dell'argomento non devono essere obbligatori nello schema BigQuery.

  • Se sono presenti campi BigQuery non presenti nello schema dell'argomento, questi campi BigQuery devono essere in modalità NULLABLE.

  • Se lo schema dell'argomento ha campi aggiuntivi che non sono presenti nello schema BigQuery e questi campi possono essere eliminati, seleziona l'opzione Elimina campi sconosciuti.

  • Puoi selezionare solo una delle proprietà dell'abbonamento, Usa schema argomento o Usa schema tabella.

Se non selezioni l'opzione Utilizza schema argomento o Utilizza schema tabella, assicurati che la tabella BigQuery abbia una colonna denominata data di tipo BYTES, STRING o JSON. Pub/Sub scrive il messaggio in questa colonna BigQuery.

Potresti non vedere immediatamente le modifiche allo schema degli argomenti Pub/Sub o allo schema della tabella BigQuery con i messaggi scritti nella tabella BigQuery. Ad esempio, se l'opzione Elimina campi sconosciuti è abilitata e un campo è presente nello schema Pub/Sub, ma non in quello BigQuery, i messaggi scritti nella tabella BigQuery potrebbero comunque non contenere il campo dopo averlo aggiunto allo schema BigQuery. Alla fine, gli schemi si sincronizzano e i messaggi successivi includono il campo.

Quando utilizzi l'opzione Utilizza lo schema dell'argomento per la sottoscrizione BigQuery, puoi anche usufruire dell'acquisizione dei dati di modifica (CDC) di BigQuery. CDC aggiorna le tabelle BigQuery elaborando e applicando le modifiche alle righe esistenti.

Per scoprire di più su questa funzionalità, vedi Aggiornare le tabelle di stream con Change Data Capture (CDC).

Per scoprire come utilizzare questa funzionalità con gli abbonamenti BigQuery, consulta Change Data Capture (CDC) di BigQuery.

Utilizza schema tabella

Questa opzione consente a Pub/Sub di utilizzare lo schema della tabella BigQuery per scrivere i campi di un messaggio JSON nelle colonne corrispondenti. Quando utilizzi questa opzione, ricordati di controllare i seguenti requisiti aggiuntivi:

  • I nomi di ogni colonna della tabella BigQuery devono contenere solo lettere (a-z, A-Z), numeri (0-9) o trattini bassi (_).

  • I messaggi pubblicati devono essere in formato JSON.

    Se una colonna della tabella BigQuery ha il tipo di dati JSON, il campo corrispondente nel messaggio Pub/Sub deve essere valido, JSON in una stringa di escape. Ad esempio, per una colonna denominata myData, il campo del messaggio deve essere "myData": "{\"key\":\"value\"}". BigQuery rifiuta i messaggi che non contengono JSON valido.