Questa pagina è stata tradotta dall'API Cloud Translation.

Caricamento dei dati dalle esportazioni di Firestore

BigQuery supporta il caricamento di dati da Firestore le esportazioni create con Firestore servizio di importazione ed esportazione gestito. Il servizio di importazione ed esportazione gestito esporta i documenti Firestore in un bucket Cloud Storage. Puoi quindi caricare i dati esportati in un Tabella BigQuery.

Limitazioni

Quando carichi i dati in BigQuery da un'esportazione di Firestore, tieni presente le seguenti limitazioni:

Il set di dati deve trovarsi nella stessa posizione del bucket Cloud Storage contenente i file di esportazione.
Puoi specificare un solo URI Cloud Storage e non puoi utilizzarne uno carattere jolly.
Affinché un'esportazione di Firestore venga caricata correttamente, i documenti nei dati di esportazione devono condividere uno schema coerente con meno di 10.000 nomi di campi univoci.
Puoi creare una nuova tabella in cui archiviare i dati oppure sovrascrivere una tabella esistente tabella. Non puoi accodare i dati dell'esportazione di Firestore a una tabella esistente.
Il comando di esportazione deve specificare un filtro collection-ids. Dati esportati senza specificare un Impossibile caricare il filtro ID raccolta in BigQuery.

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 i 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 dati in una nuova tabella o partizione BigQuery o per accodare o sovrascrivere una tabella o partizione esistente, sono necessarie le 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 il ruolo IAM Amministratore archiviazione (roles/storage.admin) nel bucket. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

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 ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Caricamento dei dati del servizio di esportazione Firestore in corso...

Puoi caricare i dati da un file di metadati di esportazione di Firestore utilizzando la console Google Cloud, lo strumento a riga di comando bq o l'API.

A volte nella console Google Cloud viene utilizzata la terminologia di Datastore e lo strumento a riga di comando bq, ma le seguenti procedure sono compatibili Firestore. Condivisione Firestore e Datastore un formato di esportazione.

Console

Nella console Google Cloud, vai alla pagina BigQuery.

Vai a BigQuery
Nel riquadro Explorer, espandi il progetto e seleziona un set di dati.
Nella sezione Informazioni sul set di dati, fai clic su Crea tabella.
Nel riquadro Crea tabella, specifica i seguenti dettagli:

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 l'URI Cloud Storage. Non puoi includere più URI nella console Google Cloud, ma sono supportati i caratteri jolly. 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 dell'esportazione Firestore deve terminare con KIND_COLLECTION_ID.export_metadata. Ad esempio, nel default_namespace_kind_Book.export_metadata, Book è la raccolta mentre default_namespace_kind_Book è il nome del file generato Firestore Se l'URI non termina con KIND_COLLECTION_ID.export_metadata, ricevi il seguente messaggio di errore: non contiene metadati di backup validi. (codice di errore: non valido).
  Nota: non utilizzare il file che termina con overall_export_metadata. Questo file non è utilizzabile da BigQuery.
2. In Formato file, seleziona Backup Cloud Datastore. Firestore e Datastore condividono il formato di esportazione.
Nella sezione Destinazione, specifica i seguenti dettagli:
1. In Set di dati, seleziona il set di dati in cui vuoi creare la tabella.
2. Nel campo Table (Tabella), inserisci il nome della tabella che vuoi creare.
3. Verifica che il campo Tipo di tabella sia impostato su Tabella nativa.
Nella sezione Schema, non è necessaria alcuna azione. Lo schema viene dedotto per Esportazione in Firestore.
(Facoltativo) Specifica le impostazioni di partizione e clustering. Per ulteriori informazioni, consulta Creare tabelle partizionate e Creare e utilizzare tabelle in cluster.
Fai clic su Opzioni avanzate e segui questi passaggi:
- Per Preferenza di scrittura, lascia selezionata l'opzione 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.
- Per 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.
Fai clic su Crea tabella.

bq

Utilizza il comando bq load con source_format impostato su DATASTORE_BACKUP. Fornisci il flag --location e imposta il valore su località. Se esegui l'overwiting una tabella esistente, aggiungi il flag --replace.

Per caricare solo campi specifici, utilizza il flag --projection_fields.

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

Sostituisci quanto segue:

LOCATION: la tua posizione. Il flag --location è facoltativo.
FORMAT: DATASTORE_BACKUP. Il backup di Datastore è l'opzione corretta per Firestore. Firestore e Datastore condividono un formato di esportazione.
DATASET: il set di dati che contiene la tabella 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: l'URI Cloud Storage.

Ad esempio, il seguente comando carica il gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata file di esportazione di Firestore 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 dell'esportazione di Firestore utilizzando l'API.

Crea una configurazione del job load che rimandi ai dati di origine in di archiviazione ideale in Cloud Storage.
Specifica la tua posizione nella proprietà location nella sezione jobReference della risorsa job.
sourceUris deve essere completamente qualificato, nel formato gs://BUCKET/OBJECT nella configurazione del job di caricamento. Il nome del file (oggetto) deve terminare con KIND_NAME.export_metadata. Per le esportazioni di Firestore è consentito un solo URI e non puoi utilizzare un carattere jolly.
Specifica il formato dei dati impostando la proprietà sourceFormat su DATASTORE_BACKUP nella configurazione del job di caricamento. Il backup di Datastore è l'opzione corretta per Firestore. Firestore Datastore condivide un formato di esportazione.
Per caricare solo campi specifici, imposta la proprietà projectionFields.
Se sovrascrivi una tabella esistente, specifica l'istruzione di scrittura impostando la proprietà writeDisposition su WRITE_TRUNCATE.

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Opzioni Firestore

Per modificare il modo in cui BigQuery analizza i dati di esportazione di Firestore, specifica la seguente opzione:

Opzione della console Google Cloud	Flag "bq"	Proprietà API BigQuery	Descrizione
Non disponibile	`--projection_fields`	`projectionFields` (Java, Python)	(Facoltativo) Un elenco separato da virgole che indica i campi dei documenti per caricare i dati da un'esportazione Firestore. Per impostazione predefinita, BigQuery carica tutti i campi. I nomi dei campi sono sensibile alle maiuscole e deve essere presente nell'esportazione. Non puoi specificare il campo percorsi all'interno di un campo della mappa come `map.foo`.

Conversione del tipo di dati

BigQuery converte i dati di ogni documento nei file di esportazione di Firestore nei tipi di dati BigQuery. La tabella seguente descrive la conversione tra i tipi di dati supportati.

Tipo di dati Firestore	Tipo di dati BigQuery
Array	RECORD
Booleano	BOOLEANO
Riferimento	RECORD
Data e ora	TIMESTAMP
Mappa	RECORD
Numero in virgola mobile	FLOAT
Punto geografico	RECORD [{"lat","FLOAT"}, {"long","FLOAT"}]
Numero intero	INTEGER
Stringa	STRING (troncato a 64 kB)

Proprietà chiave Firestore

Ogni documento in Firestore ha una chiave univoca che contiene informazioni come l'ID e il percorso del documento. BigQuery crea un tipo di dati RECORD (noto anche come STRUCT) per la chiave, con campi nidificati per ogni informazione, come descritto nella tabella seguente.

Proprietà della chiave	Descrizione	Tipo di dati BigQuery
`__key__.app`	Il nome dell'app Firestore.	STRING
`__key__.id`	L'ID del documento o `null` se `__key__.name` è impostata.	INTEGER
`__key__.kind`	L'ID raccolta del documento.	STRING
`__key__.name`	Il nome del documento o `null` se è impostato `__key__.id`.	STRING
`__key__.namespace`	Firestore non supporta gli spazi dei nomi personalizzati. Lo spazio dei nomi predefinito è rappresentato da una stringa vuota.	STRING
`__key__.path`	Il percorso del documento: la sequenza del documento e le coppie di raccolte dalla raccolta principale. Ad esempio: `"Country", "USA", "PostalCode", 10011, "Route", 1234`.	STRING