Caricamento dei dati dalle esportazioni di Datastore

BigQuery supporta il caricamento dei dati da Datastore esportazioni create utilizzando l'importazione e l'esportazione gestite di Datastore completamente gestito di Google Cloud. Puoi utilizzare il servizio gestito di importazione ed esportazione per esportare Entità Datastore in un bucket Cloud Storage. Puoi quindi caricare l'esportazione in BigQuery sotto forma di tabella.

Per scoprire come creare un file di esportazione Datastore, consulta Esportazione e importazione di entità disponibile nella documentazione di Datastore. Per informazioni su sulla pianificazione delle esportazioni, consulta la sezione Pianificazione di un'esportazione.

Nota: se intendi caricare un'esportazione di Datastore in in BigQuery, devi specificare un filtro entità comando di esportazione. I dati esportati senza specificare un filtro di entità non possono essere caricati in e BigQuery.

Puoi controllare quali proprietà devono essere caricate da BigQuery impostando la proprietà projectionFields nell'API o utilizzando il flag --projection_fields nello strumento a riga di comando bq.

Se preferisci saltare il processo di caricamento, puoi eseguire query sull'esportazione direttamente e la configurazione come origine dati esterna. Per ulteriori informazioni, vedi Origini dati esterne.

Quando carichi i dati da Cloud Storage in una tabella BigQuery, il set di dati che contiene la tabella deve trovarsi nella stessa regione o in più regioni del bucket Cloud Storage.

Limitazioni

Quando carichi i dati in BigQuery da un datastore tieni presente le seguenti restrizioni:

• Non puoi utilizzare un carattere jolly nell'URI di Cloud Storage quando specifichi File di esportazione Datastore.
• Puoi specificare un solo URI Cloud Storage durante il caricamento dei dati da Esportazioni di Datastore.
• Non puoi aggiungere dati di esportazione Datastore a una tabella esistente con uno schema definito.
• Affinché un'esportazione di Datastore venga caricata correttamente, le entità nel i dati dell'esportazione devono condividere uno schema coerente con meno di 10.000 i nomi delle proprietà.
• I dati esportati senza specificare un filtro di entità non possono essere caricati in in BigQuery. La richiesta di esportazione deve includere uno o più nomi di tipi nel filtro delle entità.
• Le dimensioni massime dei campi per Datastore esportate è di 64 kB. Quando carichi un'esportazione di Datastore, qualsiasi campo più grandi di 64 kB vengono troncati.

Prima di iniziare

Concedi ruoli IAM (Identity and Access Management) che concedono agli utenti le autorizzazioni necessarie per eseguire ogni attività in questo documento.

Autorizzazioni obbligatorie

Per caricare dati in BigQuery, devi disporre delle autorizzazioni IAM per eseguire un job di caricamento e caricare i dati nelle tabelle e nelle partizioni BigQuery. Se carichi dati da Cloud Storage, devi disporre anche delle autorizzazioni IAM per accedere al bucket che contiene i dati.

Autorizzazioni per caricare i dati in BigQuery

Per caricare i dati in una nuova tabella o partizione BigQuery oppure per aggiungere o sovrascrivere una tabella o una partizione esistente, devi disporre delle seguenti autorizzazioni IAM:

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.tables.update
• bigquery.jobs.create

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per caricare i dati in una tabella o una partizione BigQuery:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (include l'autorizzazione bigquery.jobs.create)
• bigquery.user (include l'autorizzazione bigquery.jobs.create)
• bigquery.jobUser (include l'autorizzazione bigquery.jobs.create)

Inoltre, se disponi dell'autorizzazione bigquery.datasets.create, puoi creare e aggiornare le tabelle utilizzando un job di caricamento nei set di dati che crei.

Per ulteriori informazioni su ruoli e autorizzazioni IAM in BigQuery, vedi Autorizzazioni e ruoli predefiniti.

Autorizzazioni per caricare i dati da Cloud Storage

Per ottenere le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage, chiedi all'amministratore di concederti Ruolo IAM Storage Admin (roles/storage.admin) nel bucket. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Questo ruolo predefinito contiene le autorizzazioni necessarie per caricare i dati da un bucket Cloud Storage. Per vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per caricare i dati da un bucket Cloud Storage, sono necessarie le seguenti autorizzazioni:

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

Potresti anche riuscire a ottenere queste autorizzazioni con ruoli personalizzati e altri ruoli predefiniti.

Caricamento dei dati del servizio di esportazione Datastore

Per caricare i dati da un file di metadati di esportazione di Datastore:

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.
3. Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.
4. Nel riquadro Crea tabella, specifica i seguenti dettagli:
1. Nella sezione Origine, seleziona Google Cloud Storage nell'elenco Crea tabella da. Poi segui questi passaggi:
   1. Seleziona un file dal bucket Cloud Storage o inserisci URI Cloud Storage. Non puoi includere più URI nella console Google Cloud, ma con i caratteri jolly sono supportati. Il bucket Cloud Storage deve trovarsi nello stesso posizione come il set di dati che contiene la tabella da creare, aggiungere o sovrascrivere.
      L'URI del tuo Datastore il file di esportazione deve terminare con KIND_NAME.export_metadata o export[NUM].export_metadata. Ad esempio, in default_namespace_kind_Book.export_metadata, Book è il e default_namespace_kind_Book è il nome file generato da Datastore.
   2. In Formato file, seleziona Backup Cloud Datastore.
2. Nella sezione Destinazione, specifica i seguenti dettagli:
   .
   1. In Set di dati, seleziona il set di dati in cui creare il .
   2. Nel campo Tabella, inserisci il nome della tabella da creare.
   3. Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
3. Nella sezione Schema non è necessaria alcuna azione. Lo schema viene dedotto per Esportazione di Datastore.
4. (Facoltativo) Specifica le impostazioni di partizione e clustering. Per ulteriori informazioni, vedi Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster.
5. Fai clic su Opzioni avanzate ed esegui le seguenti operazioni:
   .
   • In Write preference (Preferenza di scrittura), lascia selezionata l'opzione Write if empty (Scrivi se vuoto). Questo crea una nuova tabella e carica i dati al suo interno.
   • Se vuoi ignorare i valori in una riga che non sono presenti nello schema della tabella: Seleziona Valori sconosciuti.
   • In Crittografia, fai clic su Chiave gestita dal cliente per utilizzare una Chiave Cloud Key Management Service. Se lasci l'impostazione Chiave gestita da Google, BigQuery cripta i dati at-rest.
   Per informazioni sulle opzioni disponibili, vedi Opzioni Datastore.
6. Fai clic su Crea tabella.

bq

Usa il comando bq load con source_format impostato su DATASTORE_BACKUP. Fornisci il flag --location e imposta il valore su location.

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Sostituisci quanto segue:

• LOCATION: la tua posizione. Il flag --location è facoltativo. Per Ad esempio, se utilizzi BigQuery nella regione di Tokyo, puoi impostare il valore del flag su asia-northeast1. Puoi impostare un valore predefinito della località utilizzando file.bigqueryrc.
• FORMAT: DATASTORE_BACKUP.
• DATASET: il set di dati che contiene la tabella in in cui stai caricando i dati.
• TABLE: la tabella in cui stai caricando i dati. Se la tabella non esiste, viene creata.
• PATH_TO_SOURCE: il valore URI Cloud Storage.

Ad esempio, il seguente comando carica gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Il file di esportazione di Datastore in una tabella denominata book_data. mybucket e mydataset sono stati creati nella località multiregionale US.

bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Imposta le seguenti proprietà per caricare i dati di esportazione di Datastore utilizzando l'API.

1. Crea un job di caricamento che punta ai dati di origine in Cloud Storage.

2. Specifica la tua località nel location nella sezione jobReference della risorsa job.

3. Gli URI di origine deve essere completo, nel formato gs://[BUCKET]/[OBJECT]. Il file il nome (oggetto) deve terminare con [KIND_NAME].export_metadata. Solo uno L'URI è consentito per le esportazioni di Datastore e non puoi utilizzare un carattere jolly.

4. Specifica il formato dei dati impostando il parametro Proprietà JobConfigurationLoad.sourceFormat a DATASTORE_BACKUP.

Aggiunta o sovrascrittura di una tabella con dati Datastore

Quando carichi i dati di esportazione di Datastore in BigQuery, puoi creare una nuova tabella in cui archiviare i dati oppure sovrascrivere una . Non puoi aggiungere dati di esportazione Datastore a un modello .

Se tenti di aggiungere i dati di esportazione di Datastore a un modello tabella, i seguenti risultati di errore: Cannot append a datastore backup to a table that already has a schema. Try using the WRITE_TRUNCATE write disposition to replace the existing table.

Per sovrascrivere una tabella esistente con i dati di esportazione di Datastore:

Console

1. Nella console Google Cloud, vai alla pagina BigQuery.

   Vai a BigQuery

2. Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.
3. Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.
4. Nel riquadro Crea tabella, specifica i seguenti dettagli:
1. Nella sezione Origine, seleziona Google Cloud Storage nell'elenco Crea tabella da. Poi segui questi passaggi:
   1. Seleziona un file dal bucket Cloud Storage o inserisci URI Cloud Storage. Non puoi includere più URI nella console Google Cloud, ma con i caratteri jolly sono supportati. Il bucket Cloud Storage deve trovarsi nello stesso posizione come il set di dati che contiene la tabella da creare, aggiungere o sovrascrivere.
      L'URI del tuo Datastore il file di esportazione deve terminare con KIND_NAME.export_metadata o export[NUM].export_metadata. Ad esempio, in default_namespace_kind_Book.export_metadata, Book è il e default_namespace_kind_Book è il nome file generato da Datastore.
   2. In Formato file, seleziona Backup Cloud Datastore.
Nota: è possibile modificare lo schema della tabella quando aggiungi o sovrascriverla. Per ulteriori informazioni sulle modifiche allo schema supportate durante operazione di caricamento, consulta l'articolo Modifica degli schemi delle tabelle.
2. Nella sezione Destinazione, specifica i seguenti dettagli:
   .
   1. In Set di dati, seleziona il set di dati in cui creare il .
   2. Nel campo Tabella, inserisci il nome della tabella da creare.
   3. Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
3. Nella sezione Schema non è necessaria alcuna azione. Lo schema viene dedotto per Esportazione di Datastore.
Nota: è possibile modificare lo schema della tabella quando aggiungi o sovrascriverla. Per ulteriori informazioni sulle modifiche allo schema supportate durante dell'operazione di caricamento, vedi Modifica degli schemi delle tabelle.
4. (Facoltativo) Specifica le impostazioni di partizione e clustering. Per ulteriori informazioni, vedi Creazione di tabelle partizionate e Creazione e utilizzo di tabelle in cluster. Tu impossibile convertire una tabella in una tabella partizionata o in cluster aggiungendo o sovrascriverlo. La console Google Cloud non supporta aggiungendo o sovrascrivendo tabelle partizionate o in cluster in un job di caricamento.
5. Fai clic su Opzioni avanzate ed esegui le seguenti operazioni:
   .
   • In Preferenza di scrittura, scegli Aggiungi alla tabella o Sovrascrivi dalla tabella.
   • Se vuoi ignorare i valori in una riga che non sono presenti nello schema della tabella: Seleziona Valori sconosciuti.
   • In Crittografia, fai clic su Chiave gestita dal cliente per utilizzare una Chiave Cloud Key Management Service. Se lasci l'impostazione Chiave gestita da Google, BigQuery cripta i dati at-rest.
   Per informazioni sulle opzioni disponibili, vedi Opzioni Datastore.
6. Fai clic su Crea tabella.

bq

Usa il comando bq load con il flag --replace e con source_format impostato su DATASTORE_BACKUP. Fornisci il flag --location e imposta il valore su la tua posizione.

bq --location=LOCATION load \
--source_format=FORMAT \
--replace \
DATASET.TABLE \
PATH_TO_SOURCE

Sostituisci quanto segue:

• LOCATION: la tua posizione. Il flag --location è facoltativo. Per Ad esempio, se utilizzi BigQuery nella regione di Tokyo, puoi impostare il valore del flag su asia-northeast1. Puoi impostare un valore predefinito della località utilizzando file.bigqueryrc.
• FORMAT: DATASTORE_BACKUP.
• DATASET: il set di dati contenente la tabella in in cui stai caricando i dati.
• TABLE: la tabella che stai sovrascrivendo.
• PATH_TO_SOURCE: il valore URI Cloud Storage.

Ad esempio, il seguente comando carica gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata Il file di esportazione Datastore e sovrascrive una tabella denominata book_data:

bq load --source_format=DATASTORE_BACKUP \
--replace \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

Imposta le seguenti proprietà per caricare i dati dall'API.

1. Crea un job di caricamento che punta ai dati di origine in Cloud Storage.

2. Specifica la tua località nel location nella sezione jobReference della risorsa job.

3. Gli URI di origine deve essere completo, nel formato gs://[BUCKET]/[OBJECT]. Il file il nome (oggetto) deve terminare con [KIND_NAME].export_metadata. Solo uno L'URI è consentito per le esportazioni di Datastore e non puoi utilizzare un carattere jolly.

4. Specifica il formato dei dati impostando il parametro Proprietà JobConfigurationLoad.sourceFormat a DATASTORE_BACKUP.

5. Specifica l'istruzione di scrittura impostando il metodo Proprietà JobConfigurationLoad.writeDisposition a WRITE_TRUNCATE.

Opzioni Datastore

Per modificare la modalità di analisi dell'esportazione di Datastore da parte di BigQuery specifica la seguente opzione:

Opzione della console	flag strumento bq	Proprietà API BigQuery	Descrizione
Non disponibile	--projection_fields	projectionFields	Un elenco separato da virgole che indica quali proprietà dell'entità caricare in BigQuery da un'esportazione di Datastore. I nomi delle proprietà sono sensibili alle maiuscole e devono essere proprietà di primo livello. In caso contrario vengono specificate le proprietà, BigQuery carica tutte le proprietà. Se nessuna proprietà denominata non è stata trovata nell'esportazione di Datastore, viene restituito un errore non valido nel risultato del job. Il valore predefinito è ''.

Conversione del tipo di dati

BigQuery converte i dati di ogni entità Datastore di file di esportazione in BigQuery tipi di dati. La tabella seguente descrive la conversione tra tipi di dati.

Tipo di dati Datastore	Tipo di dati BigQuery
Array	ARRAY
Blob	BYTES
Booleano	BOOLEAN
Data e ora	TIMESTAMP
Entità incorporata	RECORD
Numero con virgola mobile	FLOAT
Punto geografico	RECORD [{"lat","DOUBLE"}, {"long","DOUBLE"}]
Numero intero	INTEGER
Chiave	RECORD
Null	STRING
Stringa di testo	STRING (troncato a 64 kB)

Proprietà chiave Datastore

Ogni entità in Datastore ha una chiave univoca che contiene informazioni come lo spazio dei nomi e il percorso. BigQuery crea un tipo di dati RECORD per la chiave, con campi nidificati per ogni elemento informazioni, come descritto nella tabella seguente.

Proprietà della chiave	Descrizione	Tipo di dati BigQuery
__key__.app	Il nome dell'app Datastore.	STRINGA
__key__.id	L'ID dell'entità o null se __key__.name è per iniziare.	INTEGER
__key__.kind	Il tipo di entità.	STRINGA
__key__.name	Il nome dell'entità o null se __key__.id è per iniziare.	STRINGA
__key__.namespace	Se l'app Datastore utilizza uno spazio dei nomi personalizzato, dello spazio dei nomi dell'entità. In caso contrario, lo spazio dei nomi predefinito è rappresentato da un stringa vuota.	STRINGA
__key__.path	Appiattito percorso ancestrale dell'entità, costituito dalla sequenza di coppie tipo-identificatore dell'entità base all'entità stessa. Ad esempio: "Country", "USA", "PostalCode", 10011, "Route", 1234.	STRINGA