Importa file Avro Spanner

Questa pagina descrive come importare i database Spanner in Spanner utilizzando la Google Cloud console. Per importare file Avro da un'altra origine, consulta Importare dati da database non Spanner.

La procedura utilizza Dataflow e importa i dati da una cartella del bucket Cloud Storage che contiene un insieme di file Avro e file manifest JSON. La procedura di importazione supporta solo i file Avro esportati da Spanner.

Per importare un database Spanner utilizzando l'API REST o il gcloud CLI, completa i passaggi nella sezione Prima di iniziare di questa pagina, quindi consulta le istruzioni dettagliate in Cloud Storage Avro to Spanner.

Prima di iniziare

Per importare 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 del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. 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 importazione sono i seguenti:

• Spanner: devi disporre di una capacità di calcolo sufficiente per supportare la quantità di dati che stai importando. Non è necessaria una capacità di calcolo aggiuntiva per importare un database, anche se potresti dover 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 importare, devi disporre di un bucket contenente i file esportati in precedenza. Non è necessario impostare una dimensione per il bucket.
• Dataflow: i job di importazione 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 importazione, 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, quindi paghi solo le risorse effettivamente utilizzate durante l'importazione. 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)
• Dataflow Worker (roles/dataflow.worker)
• Storage Admin (roles/storage.admin)
• Lettore database Spanner (roles/spanner.databaseReader)
• Amministratore database (roles/spanner.databaseAdmin)

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

(Facoltativo) Trovare la cartella del database in Cloud Storage

Per trovare la cartella contenente il database esportato nella Google Cloud console, vai al browser Cloud Storage e fai clic sul bucket che contiene la cartella esportata.

Vai al browser Cloud Storage

Il nome della cartella contenente i dati esportati 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 per la tabella Songs.

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

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

Importare un database

Per importare il database Spanner da Cloud Storage all'istanza:

1. Vai alla pagina Istanze di Spanner.

   Vai alla pagina delle istanze

2. Fai clic sul nome dell'istanza che conterrà il database importato.

3. Fai clic sulla voce di menu Importa/Esporta nel riquadro a sinistra e poi sul pulsante Importa.

4. In Scegli una cartella di origine, fai clic su Sfoglia.

5. Trova il bucket che contiene l'esportazione nell'elenco iniziale oppure fai clic Cerca per filtrare l'elenco e trovare il bucket. Fai doppio clic sul bucket per visualizzare le cartelle che contiene.

6. Trova la cartella con i file esportati e fai clic per selezionarla.

   Nota: assicurati di selezionare la cartella creata dal job di esportazione e non una cartella di livello superiore che contiene la cartella esportata.

7. Fai clic su Seleziona.

8. Inserisci un nome per il nuovo database, che Spanner crea durante la procedura di importazione. Il nome del database non può esistere già nell'istanza.

9. Scegli il dialetto per il nuovo database (GoogleSQL o PostgreSQL).

10. (Facoltativo) Per proteggere il nuovo database con una chiave di crittografia gestita dal cliente, fai clic su Mostra opzioni di crittografia e seleziona Utilizza una chiave di crittografia gestita dal cliente (CMEK). Quindi, seleziona una chiave dall'elenco a discesa.

11. Seleziona una regione dal menu a discesa Scegli una regione per il job di importazione.

    Nota: per evitare addebiti per il trasferimento di dati in uscita, scegli una regione che si sovrappone alla località del bucket Cloud Storage. Per ulteriori informazioni, consulta la sezione Scegliere una regione di seguito.

12. (Facoltativo) Per criptare lo stato della pipeline Dataflow con una chiave di crittografia gestita dal cliente, fai clic su Mostra opzioni di crittografia e seleziona Utilizza una chiave di crittografia gestita dal cliente (CMEK). Quindi, seleziona una chiave dall'elenco a discesa.

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

14. Fai clic su Importa.

    La Google Cloud console mostra la pagina Dettagli database, che ora mostra una casella che descrive il job di importazione, incluso il tempo trascorso del job:

    

Al termine o all'interruzione del job, la Google Cloud console mostra un messaggio nella pagina Dettagli database. Se il job va a buon fine, viene visualizzato un messaggio di successo:

Nota: al termine del job di importazione di Dataflow, Spanner crea indici e chiavi esterne per il database importato. Durante la creazione dell'indice, la Google Cloud console mostra un'icona in corso per indicare che è in corso un'operazione a lunga esecuzione. L'icona si trova accanto al nome dell'indice, nella gerarchia del database a sinistra della pagina Dettagli database. Quando l'icona in corso diventa l'icona dell'indice , la creazione dell'indice è completata. Puoi eseguire una query su SPANNER_STATE nella INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS per visualizzare l'avanzamento della creazione delle chiavi esterne.

Se il job non va a buon fine, viene visualizzato un messaggio di errore:

Se il job non va a buon fine, controlla i log di Dataflow del job per i dettagli sull'errore e consulta Risolvere i problemi relativi ai job di importazione non riusciti.

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

Spanner utilizza la definizione di ogni colonna generata nello schema Avro per ricreare la colonna. Spanner calcola automaticamente i valori delle colonne generate durante l'importazione.

Allo stesso modo, Spanner utilizza la definizione di ogni flusso di modifiche nello schema Avro per ricrearlo durante l'importazione. I dati delle modifiche in tempo reale non vengono esportati né importati tramite Avro, quindi tutte le modifiche in tempo reale associate a un database appena importato non avranno record di dati di modifica.

Nota sull'importazione di sequenze

Ogni sequenza (GoogleSQL, PostgreSQL) esportata da Spanner utilizza la funzione GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) per acquisire il suo stato attuale. Spanner aggiunge un buffer di 1000 al contatore e scrive il nuovo valore del contatore nelle proprietà del campo del record. Tieni presente che questo è solo un approccio di massima per evitare errori di valori duplicati che potrebbero verificarsi dopo l'importazione. Modifica il contatore della sequenza effettiva se ci sono più scritture nel database di origine durante l'esportazione dei dati.

Durante l'importazione, la sequenza inizia da questo nuovo contatore anziché dal contatore presente nello schema. Se necessario, puoi utilizzare l'istruzione ALTER SEQUENCE (GoogleSQL, PostgreSQL) per aggiornare a un nuovo contatore.

Nota sull'importazione di tabelle interfoliate e chiavi esterne

Il job Dataflow può importare tabelle interfoliate, consentendoti di conservare le relazioni padre-figlio dal file di origine. Tuttavia, i vincoli di chiave esterna non vengono applicati durante il caricamento dei dati. Il job Dataflow crea tutte le chiavi esterne necessarie al termine del caricamento dei dati.

Se hai vincoli di chiave esterna nel database Spanner prima dell'inizio dell'importazione, potresti riscontrare errori di scrittura a causa di violazioni dell'integrità referenziale. Per evitare errori di scrittura, valuta la possibilità di eliminare le chiavi esterne esistenti prima di avviare la procedura di importazione.

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 per il job di importazione non è disponibile una regione colocalizzata 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 per il trasferimento di dati più bassi.

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

Dopo aver avviato un job di importazione, 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 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 va a buon fine, 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 importazione 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 scrittura del 99% nella scheda Monitoraggio del database Spanner nella Google Cloud console. Se mostra valori elevati (più secondi), allora significa che l'istanza è sovraccaricata, causando timeout e errori di scrittura.

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'importazione utilizzando il modello Dataflow Cloud Storage Avro to Spanner 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-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=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 importazione a esecuzione lenta

Se hai seguito i suggerimenti nelle impostazioni iniziali, in genere non devi 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 di 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 di Spanner.

Fattori che influiscono sulle prestazioni del job di importazione

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

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

• Schema del database Spanner, tra cui:

  • Il numero di tabelle
  • Le dimensioni delle righe
  • Il numero di indici secondari
  • Il numero di chiavi esterne
  • Il numero di modifiche in tempo reale

Tieni presente che la creazione di indici e chiave esterna continua dopo il completamento del job di importazione di Dataflow. I flussi di modifiche in tempo reale vengono creati prima del completamento del job di importazione, ma dopo l'importazione di tutti i dati.

• 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: per ottenere buone prestazioni, sono necessari worker Dataflow ottimali. Utilizzando la scalabilità automatica, Dataflow sceglie il numero di worker per il job in base alla quantità di lavoro da svolgere. Tuttavia, il numero di worker 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, l'avanzamento è più lento, ma il job dovrebbe comunque essere completato. La scalabilità automatica può sovraccaricare Spanner, causando errori quando è presente una grande quantità di dati da importare.

• Carico esistente su Spanner: un job di importazione aggiunge un carico di CPU significativo 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.

Ottimizzare i worker per ottenere buone prestazioni di importazione

Quando avvii un job di importazione di Spanner, i worker Dataflow devono essere impostati su un valore ottimale per ottenere buone prestazioni. Un numero eccessivo di worker sovraccarica Spanner, mentre un numero insufficiente di worker comporta prestazioni di importazione deludenti.

Il numero massimo di worker dipende in gran parte dalle dimensioni dei dati, ma idealmente l'utilizzo totale della CPU di Spanner dovrebbe essere compreso tra il 70% e il 90%. Questo offre un buon equilibrio tra l'efficienza di Spanner e il completamento del job senza errori.

Per raggiungere questo target di utilizzo nella maggior parte degli schemi e degli scenari, consigliamo un numero massimo di vCPU worker compreso tra 4 e 6 volte il numero di nodi Spanner.

Ad esempio, per un'istanza Spanner a 10 nodi, utilizzando worker n1-standard-2, imposteresti il numero massimo di worker su 25, ottenendo 50 vCPU.