Questa pagina è stata tradotta dall'API Cloud Translation.

Creare set di dati esterni Spanner

Questo documento descrive come creare un set di dati esterno (noto anche come set di dati federato) in BigQuery collegato a un database esistente in Spanner.

Un set di dati esterno è una connessione tra BigQuery e un a livello del set di dati. Ti consente di eseguire query sui dati transazionali in Spanner con GoogleSQL senza spostare dati da Spanner allo spazio di archiviazione BigQuery.

Le tabelle di un set di dati esterno vengono compilate automaticamente dalle tabelle dell'origine dati esterna corrispondente. Puoi eseguire query su queste tabelle direttamente in BigQuery, ma non puoi apportare modifiche, aggiunte o eliminazioni. Tuttavia, tutti gli aggiornamenti apportati nell'origine dati esterna vengono automaticamente riportati in BigQuery.

Autorizzazioni obbligatorie

Per ottenere l'autorizzazione necessaria per creare un set di dati esterno, chiedi all'amministratore di concederti Ruolo IAM Utente BigQuery (roles/bigquery.user). Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene bigquery.datasets.create autorizzazione, che è obbligatorio per creare un set di dati esterno.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Per ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, vedi Introduzione a IAM.

Creare un set di dati esterno

Per creare un set di dati esterno:

Console

Apri la pagina BigQuery nella console Google Cloud.

Vai alla pagina di BigQuery
Nel riquadro Explorer, seleziona il progetto in cui vuoi creare il set di dati.
Espandi l'opzione Azioni e fai clic su Crea set di dati.
Nella pagina Crea set di dati:
- In ID set di dati, inserisci un nome univoco per il set di dati.
- Per Tipo di località, scegli una località per il set di dati, ad esempio us-central1 o us multiregionale. Una volta creato un set di dati, la posizione non può essere modificata.
- Per Set di dati esterno:
  - Seleziona la casella accanto a Collega a un set di dati esterno.
  - In Tipo di set di dati esterno, seleziona Spanner.
  - In Origine esterna, inserisci l'identificatore completo del tuo database Spanner nel seguente formato: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Ad esempio: projects/my_project/instances/my_instance/databases/my_database.
  - Se vuoi, inserisci il nome di un ruolo database Spanner in Ruolo database. Per saperne di più, leggi i ruoli di database utilizzati per creare connessioni Spanner
- Lascia invariate le altre impostazioni predefinite.
Fai clic su Crea set di dati.

SQL

Utilizza la Dichiarazione DDL (Data Definition Language) di CREATE EXTERNAL SCHEMA.

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nell'editor query, inserisci la seguente istruzione:
```
CREATE EXTERNAL SCHEMA DATASET_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
```
Sostituisci quanto segue:
- DATASET_NAME: il nome del nuovo set di dati in in BigQuery.
- SPANNER_EXTERNAL_SOURCE: il nome completo e qualificato del database Spanner, con un prefisso che identifica il nel seguente formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Ad esempio: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database o google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
- LOCATION: la posizione del nuovo set di dati in BigQuery, ad esempio us-central1. Una volta creato un set di dati, non puoi modificarne la posizione.
Fai clic su Esegui.

Per ulteriori informazioni su come eseguire query, consulta Eseguire una query interattiva.

bq

In un ambiente a riga di comando, crea un set di dati esterno utilizzando Comando bq mk:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

Sostituisci quanto segue:

LOCATION: la posizione del nuovo set di dati in BigQuery, ad esempio us-central1. Dopo aver creato non puoi modificarne la località. Puoi impostare un valore predefinito per la posizione utilizzando il file .bigqueryrc.
SPANNER_EXTERNAL_SOURCE: il nome completo e qualificato del database Spanner, con un prefisso che identifica la fonte, nel seguente formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Ad esempio: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database o google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
DATASET_NAME: il nome del nuovo set di dati in in BigQuery. Per creare un set di dati in un progetto diverso da quello predefinito, aggiungi l'ID progetto al nome del set di dati nel seguente formato: PROJECT_ID:DATASET_NAME.

Terraform

Utilizza la risorsa google_bigquery_dataset.

Per autenticarti a BigQuery, configura le credenziali predefinite per l'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

Nell'esempio seguente viene creato un set di dati esterno Spanner:

resource "google_bigquery_dataset" "dataset" {
  provider                    = google-beta
  dataset_id                  = "example_dataset"
  friendly_name               = "test"
  description                 = "This is a test description."
  location                    = "us-central1"

external_dataset_reference {
  external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
  }
}

Per applicare la configurazione Terraform in un progetto Google Cloud, completa i passaggi nelle seguenti sezioni.

Prepara Cloud Shell

Avvia Cloud Shell.
Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.

Devi eseguire questo comando una sola volta per progetto e puoi farlo in qualsiasi directory.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione di Terraform.

Prepara la directory

Ogni file di configurazione di Terraform deve avere una propria directory (chiamata anche modulo principale).

In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve contenere .tf, ad esempio main.tf. In questo tutorial, il file è denominato main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.

Copia il codice di esempio nel file main.tf appena creato.

Se vuoi, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.
Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
Salva le modifiche.
Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.
```
terraform init
```
Facoltativamente, per utilizzare la versione più recente del provider Google, includi -upgrade :
```
terraform init -upgrade
```

Applica le modifiche

Rivedi la configurazione e verifica che le risorse che Terraform sta per creare o aggiornare corrispondano alle tue aspettative:
```
terraform plan
```
Apporta le correzioni necessarie alla configurazione.
Applica la configurazione Terraform eseguendo questo comando e inserendo yes alla richiesta:
```
terraform apply
```
Attendi finché Terraform non visualizzi il messaggio "Applicazione completata!". per creare un nuovo messaggio email.
Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud, vai alle risorse nella UI per assicurarti create o aggiornate da Terraform.

API

Chiama il metodo datasets.insert con una risorsa set di dati e un campo externalDatasetReference per il tuo database Spanner.

Tieni presente che i nomi delle tabelle nei set di dati esterni non sono sensibili alle maiuscole.

Elenca le tabelle in un set di dati esterno

Per elencare le tabelle disponibili per la query nel set di dati esterno, consulta Elenco dei set di dati.

Recupera informazioni tabella

Per informazioni sulle tabelle del set di dati esterno, ad esempio i dettagli dello schema, consulta Ottenere informazioni sulle tabelle.

Controllare l'accesso alle tabelle

I set di dati esterni di Spanner supportano le credenziali utente finale (EUC). Ciò significa che l'accesso alle tabelle Spanner da set di dati esterni è controllato da Spanner. Gli utenti possono eseguire query su queste tabelle solo se hanno l'accesso concesso in Spanner.

Eseguire query sui dati di Spanner

L'esecuzione di query sulle tabelle nei set di dati esterni è la stessa dell'esecuzione di query sulle tabelle in qualsiasi altro set di dati BigQuery. Tuttavia, le operazioni di modifica dei dati (DML) non sono supportate.

Le query sulle tabelle nei set di dati esterni di Spanner utilizzano Data Boost per impostazione predefinita e non può essere modificato. Di conseguenza, per eseguire queste query sono necessarie autorizzazioni aggiuntive.

Crea una vista in un set di dati esterno

Non puoi creare una vista in un set di dati esterno. Tuttavia, puoi creare una vista in un set di dati standard basato su una tabella in un set di dati esterno. Per ulteriori informazioni, consulta Creare visualizzazioni.

Elimina un set di dati esterno

Eliminare un set di dati esterno è come eliminare qualsiasi altro set di dati set di dati BigQuery. L'eliminazione di set di dati esterni non influisce sulle tabelle nel database Spanner. Per ulteriori informazioni, consulta la sezione Eliminare i set di dati.

Limitazioni

Si applicano le limitazioni delle query federate di BigQuery.
Se una tabella in un database Spanner contiene una colonna di un tipo non supportato da BigQuery non sarà più accessibile su BigQuery.
Non puoi aggiungere, eliminare o aggiornare dati o metadati nelle tabelle di un Set di dati esterno di Spanner.
Non puoi creare nuove tabelle, visualizzazioni o viste materializzate in un set di dati esterno Spanner.
INFORMATION_SCHEMA visualizzazioni non sono supportati.
Memorizzazione nella cache dei metadati non è supportato.
Le impostazioni a livello di set di dati relative ai valori predefiniti per la creazione delle tabelle influisce sui set di dati esterni perché non puoi creare tabelle manualmente.
I database Spanner che utilizzano il dialetto PostgreSQL non sono supportati.
Le API Write e Read non sono supportate.
La sicurezza a livello di riga, la sicurezza a livello di colonna e il mascheramento dei dati non sono supportati.
Le viste materializzate basate su tabelle di set di dati esterni Spanner non sono supportate.
L'integrazione con Dataplex non è supportata. Ad esempio, i profili dei dati e le analisi della qualità dei dati non sono supportati.
I tag a livello di tabella non sono supportati.
Il completamento automatico SQL non funziona con le tabelle esterne di Spanner quando scrivi query.
Scan with Sensitive Data Protection non è supportato per i set di dati esterni.
La condivisione con Analytics Hub non è supportata per i set di dati esterni.
Puoi creare una vista autorizzata che fa riferimento al set di dati esterno Spanner. Tuttavia, quando viene eseguita una query su questa visualizzazione, l'EUC di una persona che esegue una query viene inviata a Spanner.

Passaggi successivi

Scopri di più su Query federate di Spanner.