Esportare i database da Spanner in Avro

Questa pagina descrive come esportare i database Spanner con la Google Cloud console.

Per esportare un database Spanner utilizzando l'API REST o Google Cloud CLI, completa i passaggi nella sezione Prima di iniziare di questa pagina, quindi consulta le istruzioni dettagliate in Spanner to Cloud Storage Avro nella documentazione di Dataflow. Il processo di esportazione utilizza Dataflow e scrive i dati in una cartella in un bucket Cloud Storage. La cartella risultante contiene un insieme di file Avro e file manifest JSON.

Prima di iniziare

Per esportare un database Spanner, devi prima abilitare le API Spanner, Cloud Storage, Compute Engine e Dataflow:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

Devi anche disporre di una quota sufficiente e delle autorizzazioni IAM richieste.

Requisiti di quota

I requisiti di quota per i job di esportazione sono i seguenti:

• Spanner: non è necessaria capacità di calcolo aggiuntiva per esportare un database, anche se potrebbe essere necessario aggiungere altra capacità di calcolo in modo che il job venga completato in un periodo di tempo ragionevole. Per ulteriori dettagli, consulta Ottimizzare i job.
• Cloud Storage: per esportare, devi creare un bucket per i file esportati se non ne hai già uno. Puoi farlo nella Google Cloud console, tramite la pagina Cloud Storage o durante la creazione dell'esportazione tramite la pagina Spanner. Non è necessario impostare una dimensione per il bucket.
• Dataflow: i job di esportazione sono soggetti alle stesse quote di CPU, utilizzo del disco e indirizzo IP di Compute Engine degli altri job Dataflow.

• Compute Engine: prima di eseguire il job di esportazione, devi configurare le quote iniziali per Compute Engine, che Dataflow utilizza. Queste quote rappresentano il numero massimo di risorse che consenti a Dataflow di utilizzare per il tuo job. I valori iniziali consigliati sono:

  • CPU: 200
  • Indirizzi IP in uso: 200
  • Standard Persistent Disk: 50 TB

  In genere, non devi apportare altre modifiche. Dataflow fornisce la scalabilità automatica in modo da pagare solo le risorse effettivamente utilizzate durante l'esportazione. Se il job può utilizzare più risorse, l'interfaccia utente di Dataflow mostra un'icona di avviso. Il job dovrebbe essere completato anche se è presente un'icona di avviso.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per esportare un database, chiedi all'amministratore di concederti i seguenti ruoli IAM sul account di servizio worker di Dataflow:

• Visualizzatore Cloud Spanner (roles/spanner.viewer)
• Worker Dataflow (roles/dataflow.worker)
• Amministratore spazio di archiviazione (roles/storage.admin)
• Lettore database Spanner (roles/spanner.databaseReader)
• Amministratore database (roles/spanner.databaseAdmin)

**Nota**: il ruolo Amministratore database Spanner è richiesto solo per i job di importazione.

Per utilizzare le risorse di calcolo indipendenti di Spanner Data Boost durante un'esportazione, devi disporre anche dell'autorizzazione IAM spanner.databases.useDataBoost. Per ulteriori informazioni, consulta la panoramica di Data Boost.

Esportare un database

Dopo aver soddisfatto i requisiti di quota e IAM descritti in precedenza, puoi esportare un database Spanner esistente.

Nota: è sicuro esportare un database in uso. Tuttavia, le modifiche apportate dopo che Dataflow crea una transazione Spanner non vengono acquisite dall'esportazione, perché tutti i dati esportati provengono dallo stesso snapshot del database.

Per esportare il database Spanner in un bucket Cloud Storage:

1. Vai alla pagina Istanze di Spanner.

   Vai a Istanze

2. Fai clic sul nome dell'istanza che contiene il database.

3. Fai clic sulla voce di menu Importa/Esporta nel riquadro a sinistra, quindi fai clic sul pulsante Esporta.

4. In Scegli dove archiviare l'esportazione, fai clic su Sfoglia.

5. Se non hai già un bucket Cloud Storage per l'esportazione:

   1. Fai clic su Nuovo bucket .
   2. Inserisci un nome per il bucket. I nomi dei bucket devono essere univoci in Cloud Storage.
   3. Seleziona una classe di archiviazione e una località predefinite, quindi fai clic su Crea.
   4. Fai clic sul bucket per selezionarlo.

   Se hai già un bucket, selezionalo dall'elenco iniziale o fai clic su Cerca per filtrare l'elenco, quindi fai clic sul bucket per selezionarlo.

6. Fai clic su Seleziona.

7. Seleziona il database che vuoi esportare nel menu a discesa Scegli un database da esportare.

8. (Facoltativo) Per esportare il database da un momento precedente, seleziona la casella e inserisci un timestamp.

9. Seleziona una regione nel menu a discesa Scegli una regione per il job di esportazione.

   Nota: per evitare addebiti per il trasferimento di dati, scegli una regione che si sovrappone alla configurazione dell'istanza. Per ulteriori informazioni, consulta Scegliere una regione.

10. (Facoltativo) Per criptare lo stato della pipeline Dataflow con una chiave di crittografia gestita dal cliente:

    1. Fai clic su Mostra opzioni di crittografia.
    2. Seleziona Usa chiave di crittografia gestita dal cliente (CMEK).
    3. Seleziona la chiave dall'elenco a discesa.

    Questa opzione non influisce sulla crittografia a livello di bucket Cloud Storage di destinazione. Per abilitare CMEK per il bucket Cloud Storage, consulta Utilizzare CMEK con Cloud Storage.

11. (Facoltativo) Per esportare utilizzando Spanner Data Boost, seleziona la casella di controllo Usa Spanner Data Boost. Per ulteriori informazioni, consulta la panoramica di Data Boost.

12. (Facoltativo) Seleziona la casella di controllo in Conferma addebiti per riconoscere che sono previsti addebiti aggiuntivi rispetto a quelli sostenuti dall'istanza Spanner esistente.

13. Fai clic su Esporta.

    La Google Cloud console mostra la pagina Importazione/esportazione database, che ora mostra una voce per il job di esportazione nell'elenco dei job di importazione/esportazione, inclusa la durata del job:

    

Al termine o all'interruzione del job, lo stato viene aggiornato nell'elenco Importa/Esporta. Se il job è stato completato correttamente, viene visualizzato lo stato Completato:

Se il job non è riuscito, viene visualizzato lo stato Non riuscito:

Per visualizzare i dettagli dell'operazione Dataflow per il job, fai clic sul nome del job nella colonna Nome job Dataflow.

Se il job non riesce, controlla i log di Dataflow del job per i dettagli dell'errore.

Per evitare addebiti per Cloud Storage per i file creati dal job di esportazione non riuscito, elimina la cartella e i relativi file. Per informazioni su come trovare la cartella, consulta Visualizzare l' esportazione.

Nota sull'esportazione di colonne generate e modifiche in tempo reale

I valori in una colonna generata archiviata non vengono esportati. La definizione della colonna viene esportata nello schema Avro come campo di record di tipo null, con la definizione della colonna come proprietà personalizzate del campo. Finché l'operazione di backfill di una colonna generata appena aggiunta non viene completata, la colonna generata viene ignorata come se non esistesse nello schema.

Gli stream di modifiche in tempo reale esportati come file Avro contengono solo lo schema degli stream di modifiche in tempo reale e non i record di modifiche dei dati.

Nota sull'esportazione delle sequenze

Le sequenze (GoogleSQL, PostgreSQL) sono oggetti schema che utilizzi per generare valori interi univoci. Spanner esporta ogni oggetto schema nello schema Avro come campo di record, con il tipo di sequenza, l'intervallo saltato e il contatore come proprietà del campo. Tieni presente che, per impedire che una sequenza venga reimpostata e generi valori duplicati dopo l'importazione, durante l'esportazione dello schema, la GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) funzione acquisisce il contatore della sequenza. Spanner aggiunge un buffer di 1000 al contatore e scrive il nuovo valore del contatore nel campo del record. Questo approccio evita errori di valori duplicati che potrebbero verificarsi dopo l'importazione. Se vengono eseguite più scritture nel database di origine durante l'esportazione dei dati, devi modificare il contatore della sequenza effettiva utilizzando l'istruzione ALTER SEQUENCE (GoogleSQL, PostgreSQL) .

Durante l'importazione, la sequenza inizia da questo nuovo contatore anziché dal contatore trovato nello schema. In alternativa, puoi utilizzare l'ALTER SEQUENCE (GoogleSQL, PostgreSQL) istruzione per aggiornare la sequenza con un nuovo contatore.

Visualizzare l'esportazione in Cloud Storage

Per visualizzare la cartella che contiene il database esportato nella Google Cloud console, vai al browser Cloud Storage e scegli il bucket selezionato in precedenza:

Vai al browser di archiviazione

Il bucket ora contiene una cartella con il database esportato. Il nome della cartella inizia con l'ID dell'istanza, il nome del database e il timestamp del job di esportazione. La cartella contiene:

• Un file spanner-export.json
• Un file TableName-manifest.json per ogni tabella nel database esportato.

• Uno o più TableName.avro-#####-of-##### file. Il primo numero nell'estensione .avro-#####-of-##### rappresenta l'indice del file Avro, a partire da zero, e il secondo rappresenta il numero di file Avro generati per ogni tabella.

  Ad esempio, Songs.avro-00001-of-00002 è il secondo di due file che contengono i dati della tabella Songs.

• Un file ChangeStreamName-manifest.json per ogni stream di modifiche nel database esportato.

• Un ChangeStreamName.avro-00000-of-00001 file per ogni stream di modifiche. Questo file contiene dati vuoti con solo lo schema Avro dello stream di modifiche.

Scegliere una regione per il job di importazione

Potresti voler scegliere una regione diversa in base alla località del bucket Cloud Storage. Per evitare addebiti per il trasferimento di dati in uscita, scegli una regione che corrisponda alla località del bucket Cloud Storage.

• Se la località del bucket Cloud Storage è una regione, puoi usufruire dell'utilizzo senza costi della rete scegliendo la stessa regione per il job di importazione, a condizione che la regione sia disponibile.

• Se la località del bucket Cloud Storage è a due regioni, puoi usufruire dell'utilizzo senza costi della rete scegliendo una delle due regioni che compongono la località a due regioni per il job di importazione, a condizione che una delle regioni sia disponibile.

• Se una regione in co-location non è disponibile per il job di importazione o se la località del bucket Cloud Storage è una multiregione, vengono applicati addebiti per il trasferimento di dati in uscita. Consulta i prezzi del trasferimento di dati di Cloud Storage per scegliere una regione che comporti gli addebiti più bassi per il trasferimento di dati.

Esportare un sottoinsieme di tabelle

Se vuoi esportare solo i dati di determinate tabelle e non l'intero database, puoi specificare queste tabelle durante l'esportazione. In questo caso, Spanner esporta l'intero schema del database, inclusi i dati delle tabelle specificate, lasciando tutte le altre tabelle presenti ma vuote nel file esportato.

Puoi specificare un sottoinsieme di tabelle da esportare utilizzando la pagina Dataflow nella Google Cloud console o gcloud CLI. (La pagina Spanner non fornisce questa azione.)

Se esporti i dati di una tabella che è figlia di un'altra tabella, devi esportare anche i dati della tabella padre. Se i genitori non vengono esportati, il job di esportazione non riesce.

Per esportare un sottoinsieme di tabelle, avvia l'esportazione utilizzando il modello Dataflow's Spanner to Cloud Storage Avro e specifica le tabelle utilizzando la pagina Dataflow nella console Google Cloud o gcloud CLI, come descritto di seguito:

Console

Se utilizzi la pagina Dataflow nella Google Cloud console, il Nome/i tabella/e Cloud Spanner parametro si trova nella Parametri facoltativi sezione della Crea job da modello pagina. È possibile specificare più tabelle in un formato separato da virgole.

Vai a Dataflow

gcloud

Esegui il gcloud dataflow jobs run comando e specifica l'argomento tableNames. Ad esempio:

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=table1,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

La specifica di più tabelle in gcloud richiede l'escape degli argomenti di tipo dizionario. L'esempio seguente utilizza '|' come carattere di escape:

 gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Il parametro shouldExportRelatedTables è un'opzione pratica per esportare automaticamente tutte le tabelle padre delle tabelle scelte. Ad esempio, in questa gerarchia di schemi con le tabelle Singers, Albums e Songs, devi specificare solo Songs. L'opzione shouldExportRelatedTables esporterà anche Singers e Albums perché Songs è un discendente di entrambe.

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Visualizzare o risolvere i problemi relativi ai job nell'interfaccia utente di Dataflow

Dopo aver avviato un job di esportazione, puoi visualizzare i dettagli del job, inclusi i log, nella sezione Dataflow della Google Cloud console.

Visualizzare i dettagli del job Dataflow

Per visualizzare i dettagli di tutti i job di importazione o esportazione eseguiti nell'ultima settimana, inclusi i job in esecuzione:

1. Vai alla pagina Panoramica database del database.
2. Fai clic sulla voce di menu del riquadro a sinistra Importa/Esporta. La pagina Importa/Esporta del database mostra un elenco dei job recenti.

3. Nella pagina Importa/Esporta del database, fai clic sul nome del job nella colonna Nome job Dataflow:

   

   La Google Cloud console mostra i dettagli del job Dataflow.

Per visualizzare un job eseguito più di una settimana fa:

1. Vai alla pagina dei job Dataflow nella Google Cloud console.

   Vai a Job

2. Trova il job nell'elenco, quindi fai clic sul suo nome.

   La Google Cloud console mostra i dettagli del job Dataflow.

Nota: i job dello stesso tipo per lo stesso database hanno lo stesso nome. Puoi distinguere i job in base ai valori nelle colonne Ora di inizio o Ora di fine.

Visualizzare i log di Dataflow per il job

Per visualizzare i log di un job Dataflow, vai alla pagina dei dettagli del job, quindi fai clic su Log a destra del nome del job.

Se un job non riesce, cerca gli errori nei log. Se sono presenti errori, il conteggio degli errori viene visualizzato accanto a Log:

Per visualizzare gli errori del job:

1. Fai clic sul conteggio degli errori accanto a Log.

   La Google Cloud console mostra i log del job. Potresti dover scorrere per visualizzare gli errori.

2. Individua le voci con l'icona di errore .

3. Fai clic su una singola voce di log per espanderne i contenuti.

Per ulteriori informazioni sulla risoluzione dei problemi relativi ai job Dataflow, consulta Risolvere i problemi relativi alla pipeline.

Risolvere i problemi relativi ai job di esportazione non riusciti

Se visualizzi i seguenti errori nei log dei job:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Controlla la latenza di lettura del 99% nella scheda Monitoraggio del database Spanner nella Google Cloud console. Se mostra valori elevati (più secondi), allora significa che l'istanza è sovraccarica, causando il timeout e l'errore delle letture.

Una delle cause dell'elevata latenza è che il job Dataflow viene eseguito utilizzando troppi worker, il che comporta un carico eccessivo sull'istanza Spanner.

Per specificare un limite al numero di worker Dataflow, anziché utilizzare la scheda Importa/Esporta nella pagina dei dettagli dell'istanza del database Spanner nella Google Cloud console, devi avviare l'esportazione utilizzando il modello Dataflow Spanner to Cloud Storage Avro e specificare il numero massimo di worker come descritto di seguito:

Console

Se utilizzi la console Dataflow, il parametro Worker massimi si trova nella sezione Parametri facoltativi della pagina Crea job da modello.

Vai a Dataflow

gcloud

Esegui il gcloud dataflow jobs run comando e specifica l'argomento max-workers. Ad esempio:

  gcloud dataflow jobs run my-export-job \
    --gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,outputDir=gs://my-gcs-bucket' \
    --max-workers=10 \
    --network=network-123

Risolvere i problemi relativi agli errori di rete

Quando esporti i database Spanner, potrebbe verificarsi il seguente errore:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Questo errore si verifica perché Spanner presuppone che tu voglia utilizzare una rete VPC in modalità automatica denominata default nello stesso progetto del job Dataflow. Se non hai una rete VPC predefinita nel progetto o se la tua rete VPC è in una rete VPC in modalità personalizzata, devi creare un job Dataflow e specificare una rete o una subnet alternativa.

Ottimizzare i job di esportazione a esecuzione lenta

Se hai seguito i suggerimenti nelle impostazioni iniziali, in genere non dovresti apportare altre modifiche. Se il job viene eseguito lentamente, puoi provare alcune altre ottimizzazioni:

• Ottimizzare la località del job e dei dati: esegui il job Dataflow nella stessa regione in cui si trovano l'istanza Spanner e il bucket Cloud Storage.

• Garantire risorse Dataflow sufficienti: se le quote di Compute Engine pertinenti limitano le risorse del job Dataflow, la pagina Dataflow del job nella Google Cloud console mostra un'icona di avviso e messaggi di log:

  

  In questa situazione, l'aumento delle quote per CPU, indirizzi IP in uso e Standard Persistent Disk potrebbe ridurre il tempo di esecuzione del job, ma potresti sostenere maggiori addebiti per Compute Engine.

• Controllare l'utilizzo della CPU di Spanner: se l'utilizzo della CPU per l'istanza è superiore al 65%, puoi aumentare la capacità di calcolo in quell'istanza. La capacità aggiunge altre risorse Spanner e il job dovrebbe accelerare, ma sostieni maggiori addebiti per Spanner.

Fattori che influiscono sulle prestazioni dei job di esportazione

Diversi fattori influenzano il tempo necessario per completare un job di esportazione.

• Dimensioni del database Spanner: l'elaborazione di più dati richiede più tempo e risorse.

• Schema del database Spanner, tra cui:

  • Il numero di tabelle
  • La dimensione delle righe
  • Il numero di indici secondari
  • Il numero di chiavi esterne
  • Il numero di modifiche in tempo reale

• Località dei dati: i dati vengono trasferiti tra Spanner e Cloud Storage utilizzando Dataflow. Idealmente, tutti e tre i componenti si trovano nella stessa regione. Se i componenti non si trovano nella stessa regione, lo spostamento dei dati tra le regioni rallenta il job.

• Numero di worker Dataflow: i worker Dataflow ottimali sono necessari per prestazioni ottimali. Utilizzando la scalabilità automatica, Dataflow sceglie il numero di worker per il job in base alla quantità di lavoro da svolgere. Il numero di worker, tuttavia, sarà limitato dalle quote per CPU, indirizzi IP in uso e Standard Persistent Disk. L'interfaccia utente di Dataflow mostra un'icona di avviso se rileva limiti di quota. In questa situazione, i progressi sono più lenti, ma il job dovrebbe comunque essere completato.

• Carico esistente su Spanner: un job di esportazione in genere aggiunge un carico leggero a un'istanza Spanner. Se l'istanza ha già un carico esistente sostanziale, il job viene eseguito più lentamente.

• Quantità di capacità di calcolo di Spanner: se l'utilizzo della CPU per l'istanza è superiore al 65%, il job viene eseguito più lentamente.