Esta página foi traduzida pela API Cloud Translation.

Carregar dados de exportações do Firestore

O BigQuery suporta o carregamento de dados de exportações do Firestore criadas através do serviço de importação e exportação gerido do Firestore. O serviço de importação e exportação gerido exporta documentos do Firestore para um contentor do Cloud Storage. Em seguida, pode carregar os dados exportados para uma tabela do BigQuery.

Limitações

Quando carrega dados para o BigQuery a partir de uma exportação do Firestore, tenha em atenção as seguintes restrições:

O conjunto de dados tem de estar na mesma localização que o contentor do Cloud Storage que contém os ficheiros de exportação.
Só pode especificar um URI do Cloud Storage e não pode usar um caráter universal de URI.
Para que uma exportação do Firestore seja carregada corretamente, os documentos nos dados de exportação têm de partilhar um esquema consistente com menos de 10 000 nomes de campos únicos.
Pode criar uma nova tabela para armazenar os dados ou substituir uma tabela existente. Não pode acrescentar dados de exportação do Firestore a uma tabela existente.
O seu comando de exportação tem de especificar um filtro collection-ids. Não é possível carregar no BigQuery dados exportados sem especificar um filtro de ID de recolha.

Antes de começar

Conceda funções de gestão de identidade e acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento.

Autorizações necessárias

Para carregar dados para o BigQuery, precisa de autorizações da IAM para executar uma tarefa de carregamento e carregar dados para tabelas e partições do BigQuery. Se estiver a carregar dados do Cloud Storage, também precisa de autorizações de IAM para aceder ao contentor que contém os seus dados.

Autorizações para carregar dados para o BigQuery

Para carregar dados para uma nova tabela ou partição do BigQuery, ou para anexar ou substituir uma tabela ou uma partição existente, precisa das seguintes autorizações de IAM:

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

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para carregar dados para uma tabela ou uma partição do BigQuery:

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin (inclui a autorização bigquery.jobs.create)
bigquery.user (inclui a autorização bigquery.jobs.create)
bigquery.jobUser (inclui a autorização bigquery.jobs.create)

Além disso, se tiver a autorização bigquery.datasets.create, pode criar e atualizar tabelas através de uma tarefa de carregamento nos conjuntos de dados que criar.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Autorizações para carregar dados do Cloud Storage

Para receber as autorizações de que precisa para carregar dados de um contentor do Cloud Storage, peça ao seu administrador para lhe conceder a função de IAM Administrador de armazenamento (roles/storage.admin) no contentor. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para carregar dados a partir de um contentor do Cloud Storage. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para carregar dados de um contentor do Cloud Storage:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Carregar dados do serviço de exportação do Firestore

Pode carregar dados a partir de um ficheiro de metadados de exportação do Firestore através da Google Cloud consola, da ferramenta de linhas de comando bq ou da API.

Por vezes, a terminologia do Datastore é usada na Google Cloud consola e na ferramenta de linhas de comando bq, mas os procedimentos seguintes são compatíveis com ficheiros de exportação do Firestore. O Firestore e o Datastore partilham um formato de exportação.

Consola

Na Google Cloud consola, aceda à página BigQuery.

Aceda ao BigQuery
No painel Explorador, expanda o seu projeto e, de seguida, selecione um conjunto de dados.
Na secção Informações do conjunto de dados, clique em Criar tabela.
No painel Criar tabela, especifique os seguintes detalhes:

Na secção Origem, selecione Google Cloud Storage na lista Criar tabela a partir de. Em seguida, faça o seguinte:
1. Selecione um ficheiro do contentor do Cloud Storage ou introduza o URI do Cloud Storage. Não pode incluir vários URIs na Google Cloud consola, mas os carateres universais são suportados. O contentor do Cloud Storage tem de estar na mesma localização que o conjunto de dados que contém a tabela que quer criar, acrescentar ou substituir.
  O URI do ficheiro de exportação do Firestore tem de terminar com KIND_COLLECTION_ID.export_metadata. Por exemplo, em default_namespace_kind_Book.export_metadata, Book é o ID da coleção e default_namespace_kind_Book é o nome do ficheiro gerado pelo Firestore. Se o URI não terminar com KIND_COLLECTION_ID.export_metadata, recebe a seguinte mensagem de erro: não contém metadados de cópia de segurança válidos. (Código de erro: inválido).
  Nota: não use o ficheiro que termina em overall_export_metadata. Este ficheiro não pode ser usado pelo BigQuery.
2. Para Formato de ficheiro, selecione Cópia de segurança do Cloud Datastore. O Firestore e o Datastore partilham o formato de exportação.
Na secção Destino, especifique os seguintes detalhes:
1. Para Conjunto de dados, selecione o conjunto de dados no qual quer criar a tabela.
2. No campo Tabela, introduza o nome da tabela que quer criar.
3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
Na secção Esquema, não é necessária nenhuma ação. O esquema é inferido para uma exportação do Firestore.
Opcional: especifique as definições de partição e cluster. Para mais informações, consulte os artigos Criar tabelas particionadas e Criar e usar tabelas agrupadas.
Clique em Opções avançadas e faça o seguinte:
- Para Preferência de escrita, deixe a opção Escrever se estiver vazio selecionada. Esta opção cria uma nova tabela e carrega os seus dados na mesma.
- Se quiser ignorar valores numa linha que não estejam presentes no esquema da tabela, selecione Valores desconhecidos.
- Para Encriptação, clique em Chave gerida pelo cliente para usar uma chave do Cloud Key Management Service. Se deixar a definição Google-managed key, o BigQuery encripta os dados em repouso.
Clique em Criar tabela.

bq

Use o comando bq load com source_format definido como DATASTORE_BACKUP. Forneça a flag --location e defina o valor para a sua localização. Se estiver a substituir uma tabela existente, adicione a flag --replace.

Para carregar apenas campos específicos, use a flag --projection_fields.

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

Substitua o seguinte:

LOCATION: a sua localização. A flag --location é opcional.
FORMAT: DATASTORE_BACKUP. A opção correta para o Firestore é a cópia de segurança do Datastore. O Firestore e o Datastore partilham um formato de exportação.
DATASET: o conjunto de dados que contém a tabela para a qual está a carregar dados.
TABLE: a tabela para a qual está a carregar dados. Se a tabela não existir, é criada.
PATH_TO_SOURCE: o URI do Cloud Storage.

Por exemplo, o comando seguinte carrega o ficheiro de exportação do Firestore numa tabela denominada book_data.gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata mybucket e mydataset foram criados na localização multirregional 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

Defina as seguintes propriedades para carregar dados de exportação do Firestore através da API.

Crie uma configuração de tarefa do load que aponte para os dados de origem no Cloud Storage.
Especifique a sua localização na propriedade location na secção jobReference do recurso de emprego.
O sourceUris tem de ser totalmente qualificado, no formato gs://BUCKET/OBJECT na configuração da tarefa de carregamento. O nome do ficheiro (objeto) tem de terminar em KIND_NAME.export_metadata. Só é permitido um URI para exportações do Firestore, e não pode usar um caráter universal.
Especifique o formato dos dados definindo a propriedade sourceFormat como DATASTORE_BACKUP na configuração da tarefa de carregamento. A opção Datastore Backup é a opção correta para o Firestore. O Firestore e o Datastore partilham um formato de exportação.
Para carregar apenas campos específicos, defina a propriedade projectionFields.
Se estiver a substituir uma tabela existente, especifique a disposição de escrita definindo a propriedade writeDisposition como WRITE_TRUNCATE.

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

# 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))

Opções da Firestore

Para alterar a forma como o BigQuery analisa os dados de exportação do Firestore, especifique a seguinte opção:

Google Cloud opção de consola	flag `bq`	Propriedade da API BigQuery	Descrição
Não disponível	`--projection_fields`	`projectionFields` (Java, Python)	(Opcional) Uma lista separada por vírgulas que indica os campos do documento a carregar a partir de uma exportação do Firestore. Por predefinição, o BigQuery carrega todos os campos. Os nomes dos campos são sensíveis a maiúsculas e minúsculas e têm de estar presentes na exportação. Não pode especificar caminhos de campos num campo de mapa, como `map.foo`.

Conversão de tipo de dados

O BigQuery converte os dados de cada documento nos ficheiros de exportação do Firestore em tipos de dados do BigQuery. A tabela seguinte descreve a conversão entre os tipos de dados suportados.

Tipo de dados do Firestore	Tipo de dados do BigQuery
Matriz	RECORD
Booleano	BOOLEAN
Referência	RECORD
Data e hora	TIMESTAMP
Mapa	RECORD
Número de vírgula flutuante	FLOAT
Ponto geográfico	RECORD [{"lat","FLOAT"}, {"long","FLOAT"}]
Número inteiro	INTEGER
String	STRING (truncado para 64 KB)

Propriedades principais do Firestore

Cada documento no Firestore tem uma chave única que contém informações como o ID do documento e o caminho do documento. O BigQuery cria um tipo de dados RECORD (também conhecido como STRUCT) para a chave, com campos aninhados para cada informação, conforme descrito na tabela seguinte.

Propriedade principal	Descrição	Tipo de dados do BigQuery
`__key__.app`	O nome da app do Firestore.	STRING
`__key__.id`	O ID do documento ou `null` se `__key__.name` estiver definido.	INTEGER
`__key__.kind`	O ID da coleção do documento.	STRING
`__key__.name`	O nome do documento ou `null` se `__key__.id` estiver definido.	STRING
`__key__.namespace`	O Firestore não suporta espaços de nomes personalizados. O espaço de nomes predefinido é representado por uma string vazia.	STRING
`__key__.path`	O caminho do documento: a sequência do documento e os pares de coleções da coleção raiz. Por exemplo: `"Country", "USA", "PostalCode", 10011, "Route", 1234`.	STRING