Crie conjuntos de dados externos do Spanner

Este documento descreve como criar um conjunto de dados externo (também conhecido como conjunto de dados federado) no BigQuery que está associado a uma base de dados GoogleSQL ou PostgreSQL existente no Spanner.

Um conjunto de dados externo é uma associação entre o BigQuery e uma origem de dados externa ao nível do conjunto de dados. Permite-lhe consultar dados transacionais em bases de dados do Spanner com o GoogleSQL sem ter de copiar nem importar todos os dados do Spanner para o armazenamento do BigQuery. Estes resultados da consulta são armazenados no BigQuery.

As tabelas num conjunto de dados externo são preenchidas automaticamente a partir das tabelas na origem de dados externa correspondente. Pode consultar estas tabelas diretamente no BigQuery, mas não pode fazer modificações, adições nem eliminações. No entanto, todas as atualizações que fizer na origem de dados externa são automaticamente refletidas no BigQuery.

Quando consulta o Spanner, os resultados da consulta são guardados por predefinição em tabelas temporárias. Também podem ser guardados opcionalmente como uma nova tabela do BigQuery, juntados a outras tabelas ou unidos a tabelas existentes através da DML.

Autorizações necessárias

Para receber a autorização de que precisa para criar um conjunto de dados externo, peça ao seu administrador para lhe conceder a função de IAM de utilizador do BigQuery (roles/bigquery.user). 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 a autorização bigquery.datasets.create , que é necessária para criar um conjunto de dados externo.

Também pode obter esta autorização com funções personalizadas ou outras funções predefinidas.

Para mais informações acerca das funções e autorizações do IAM no BigQuery, consulte o artigo Introdução ao IAM.

Use uma ligação CLOUD_RESOURCE

Opcionalmente, os conjuntos de dados externos do Spanner podem usar uma CLOUD_RESOURCEligação para interagir com a sua base de dados do Spanner, para que possa conceder a um utilizador acesso aos dados do Spanner através do BigQuery, sem lhe dar acesso direto à base de dados do Spanner. Uma vez que a conta de serviço da ligação CLOUD_RESOURCE processa a obtenção de dados do Spanner, só tem de conceder aos utilizadores acesso ao conjunto de dados externo do Spanner.

Antes de criar conjuntos de dados externos do Spanner com uma ligação CLOUD_RESOURCE, faça o seguinte:

Crie uma associação

Pode criar ou usar uma associação CLOUD_RESOURCE existente para estabelecer ligação ao Spanner. Para criar a associação de recursos do Google Cloud, siga os passos na página Crie uma associação de recursos do Google Cloud.

Depois de criar a associação, abra-a e, no painel Informações de associação, copie o ID da conta de serviço. Precisa deste ID quando configura as autorizações para a ligação. Quando cria um recurso de ligação, o BigQuery cria uma conta de serviço do sistema exclusiva e associa-a à ligação.

Configure o acesso

Tem de conceder à nova ligação acesso de leitura à sua instância ou base de dados do Spanner. Recomendamos que use a função de IAM predefinida de leitor da base de dados do Cloud Spanner com o DataBoost (roles/spanner.databaseReaderWithDataBoost).

Siga estes passos para conceder acesso a funções ao nível da base de dados para a conta de serviço que copiou anteriormente da associação:

  1. Aceda à página Instâncias do Spanner.

    Aceda à página de instâncias

  2. Clique no nome da instância que contém a sua base de dados para aceder à página Detalhes da instância.

  3. No separador Vista geral, selecione a caixa de verificação da sua base de dados.
    O painel de informações é apresentado.

  4. Clique em Adicionar principal.

  5. No painel Adicionar membros, em Novos membros, introduza o ID da conta de serviço que copiou anteriormente.

  6. No campo Selecionar uma função, selecione Leitor da base de dados do Cloud Spanner com a função DataBoost.

  7. Clique em Guardar.

Crie um conjunto de dados externo

Para criar um conjunto de dados externo, faça o seguinte:

Consola

  1. Abra a página do BigQuery na Trusted Cloud consola.

    Aceda à página do BigQuery

  2. No painel Explorador, selecione o projeto onde quer criar o conjunto de dados.

  3. Expanda a opção Ações e clique em Criar conjunto de dados.

  4. Na página Criar conjunto de dados, faça o seguinte:

    • Para ID do conjunto de dados, introduza um nome exclusivo para o conjunto de dados.
    • Para Tipo de localização, escolha uma localização para o conjunto de dados, como us-central1 ou multirregião us. Depois de criar um conjunto de dados, não é possível alterar a localização.

    • Para o conjunto de dados externo, faça o seguinte:

      • Selecione a caixa junto a Associar a um conjunto de dados externo.
      • Para Tipo de conjunto de dados externo, selecione Spanner.
      • Para Origem externa, introduza o identificador completo da sua base de dados do Spanner no seguinte formato: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por exemplo: projects/my_project/instances/my_instance/databases/my_database.
      • Opcionalmente, para Função da base de dados, introduza o nome de uma função da base de dados do Spanner. Para mais informações, leia acerca das funções da base de dados usadas para criar ligações do Spanner
      • Opcionalmente, selecione a caixa junto a Usar uma ligação de recursos na nuvem para criar o conjunto de dados externo com uma ligação.

    • Deixe as outras predefinições inalteradas.

  5. Clique em Criar conjunto de dados.

SQL

Use a CREATE EXTERNAL SCHEMA declaração de linguagem de definição de dados (LDD).

  1. Na Trusted Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No editor de consultas, introduza a seguinte declaração:

    CREATE EXTERNAL SCHEMA DATASET_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
/*
  Alternatively, create with a connection:
*/
CREATE EXTERNAL SCHEMA DATASET_NAME
  WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');

    Substitua o seguinte:

    • DATASET_NAME: o nome do seu novo conjunto de dados no BigQuery.
    • SPANNER_EXTERNAL_SOURCE: o nome completo e qualificado da base de dados do Spanner, com um prefixo que identifica a origem, no seguinte formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por exemplo: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database ou google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
    • LOCATION: a localização do seu novo conjunto de dados no BigQuery, por exemplo, us-central1. Depois de criar um conjunto de dados, não pode alterar a respetiva localização.
    • (Opcional)CONNECTION_NAME: o nome da ligação ao recurso da nuvem.

  3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Num ambiente de linha de comandos, crie um conjunto de dados externo através do comando bq mk:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

Em alternativa, crie uma ligação:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    --connection_id PROJECT_ID.LOCATION.CONNECTION_NAME \
    DATASET_NAME

Substitua o seguinte:

  • LOCATION: a localização do seu novo conjunto de dados no BigQuery, por exemplo, us-central1. Depois de criar um conjunto de dados, não pode alterar a respetiva localização. Pode definir um valor de localização predefinido através do ficheiro .bigqueryrc.
  • SPANNER_EXTERNAL_SOURCE: o nome completo e qualificado da base de dados do Spanner, com um prefixo que identifica a origem, no seguinte formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por exemplo: google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database ou google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
  • DATASET_NAME: o nome do novo conjunto de dados no BigQuery. Para criar um conjunto de dados num projeto que não seja o seu projeto predefinido, adicione o ID do projeto ao nome do conjunto de dados no seguinte formato: PROJECT_ID:DATASET_NAME.
  • (Opcional)CONNECTION_NAME: o nome da ligação ao recurso da nuvem.

Terraform

Use o google_bigquery_dataset recurso.

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.

O exemplo seguinte cria um conjunto de dados externo do Spanner:

resource "google_bigquery_dataset" "default" {
  dataset_id    = "my_external_dataset"
  friendly_name = "My external dataset"
  description   = "This is a test description."
  location      = "US"
  external_dataset_reference {
    # The full identifier of your Spanner database.
    external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
    # Must be empty for a Spanner external dataset.
    connection = ""
  }
}

Para aplicar a configuração do Terraform num Trusted Cloud projeto, conclua os passos nas secções seguintes.

Prepare o Cloud Shell

  1. Inicie o Cloud Shell.

  2. Defina o Trusted Cloud projeto predefinido onde quer aplicar as suas configurações do Terraform.

    Só tem de executar este comando uma vez por projeto e pode executá-lo em qualquer diretório.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    As variáveis de ambiente são substituídas se definir valores explícitos no ficheiro de configuração do Terraform.

Prepare o diretório

Cada ficheiro de configuração do Terraform tem de ter o seu próprio diretório (também denominado módulo raiz).

  1. No Cloud Shell, crie um diretório e um novo ficheiro nesse diretório. O nome do ficheiro tem de ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o ficheiro é denominado main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Se estiver a seguir um tutorial, pode copiar o código de exemplo em cada secção ou passo.

    Copie o exemplo de código para o ficheiro main.tf criado recentemente.

    Opcionalmente, copie o código do GitHub. Isto é recomendado quando o fragmento do Terraform faz parte de uma solução completa.

  3. Reveja e modifique os parâmetros de exemplo para aplicar ao seu ambiente.
  4. Guarde as alterações.
  5. Inicialize o Terraform. Só tem de fazer isto uma vez por diretório. 
    terraform init

    Opcionalmente, para usar a versão mais recente do fornecedor Google, inclua a opção -upgrade: 

    terraform init -upgrade

Aplique as alterações

  1. Reveja a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expetativas: 
    terraform plan

    Faça as correções necessárias à configuração.

  2. Aplique a configuração do Terraform executando o seguinte comando e introduzindo yes no comando: 
    terraform apply

    Aguarde até que o Terraform apresente a mensagem "Apply complete!" (Aplicação concluída!).

  3. Abra o seu Trusted Cloud projeto para ver os resultados. Na Trusted Cloud consola, navegue para os seus recursos na IU para se certificar de que o Terraform os criou ou atualizou.

API

Chame o método datasets.insert com um recurso de conjunto de dados definido e um campo externalDatasetReference para a sua base de dados do Spanner.

Tenha em atenção que os nomes das tabelas nos conjuntos de dados externos não são sensíveis a maiúsculas e minúsculas.

Quando cria os conjuntos de dados externos com uma ligação CLOUD_RESOURCE, tem de ter a autorização bigquery.connections.delegate (disponível na função de administrador da ligação do BigQuery) na ligação usada pelos conjuntos de dados externos.

Controle o acesso às tabelas

Os conjuntos de dados externos do Spanner suportam credenciais de utilizador final (EUC). Isto significa que o acesso às tabelas do Spanner a partir de conjuntos de dados externos é controlado pelo Spanner. Os utilizadores só podem consultar estas tabelas se tiverem acesso concedido no Spanner.

Os conjuntos de dados externos do Spanner também suportam a delegação de acesso. A delegação de acesso desvincula o acesso às tabelas do Spanner de conjuntos de dados externos e o acesso direto às tabelas do Spanner subjacentes. É usada uma associação de recursos do Cloud associada a uma conta de serviço para estabelecer ligação ao Spanner. Os utilizadores podem consultar estas tabelas do Spanner a partir de conjuntos de dados externos, mesmo que não tenham acesso concedido no Spanner.

Liste tabelas num conjunto de dados externo

Para listar as tabelas disponíveis para consulta no seu conjunto de dados externo, consulte o artigo Listar conjuntos de dados.

Obtenha informações da tabela

Para obter informações sobre as tabelas no seu conjunto de dados externo, como detalhes do esquema, consulte Obter informações da tabela.

Consulte dados do Spanner

Consultar tabelas em conjuntos de dados externos é igual a consultar tabelas em qualquer outro conjunto de dados do BigQuery. No entanto, as operações de modificação de dados (DML) não são suportadas.

As consultas em tabelas em conjuntos de dados externos do Spanner usam o Data Boost por predefinição e não podem ser alteradas. Por esse motivo, precisa de autorizações adicionais para executar essas consultas.

Crie uma vista num conjunto de dados externo

Não pode criar uma vista num conjunto de dados externo. No entanto, pode criar uma vista num conjunto de dados padrão com base numa tabela num conjunto de dados externo. Para mais informações, consulte Crie visualizações de propriedade.

Elimine um conjunto de dados externo

A eliminação de um conjunto de dados externo é igual à eliminação de qualquer outro conjunto de dados do BigQuery. A eliminação de conjuntos de dados externos não afeta as tabelas na base de dados do Spanner. Para mais informações, consulte o artigo Elimine conjuntos de dados.

Limitações

  • Aplicam-se as limitações das consultas federadas do BigQuery.
  • Só é possível aceder a tabelas de um esquema do Spanner predefinido no BigQuery. As tabelas de esquemas com nomes não são suportadas.
  • As chaves primárias e estrangeiras definidas na base de dados do Spanner não são visíveis no BigQuery.
  • Se uma tabela na base de dados do Spanner contiver uma coluna de um tipo não suportado pelo BigQuery, esta coluna não vai estar acessível no lado do BigQuery.
  • Não pode adicionar, eliminar nem atualizar dados ou metadados em tabelas num conjunto de dados externo do Spanner.
  • Não pode criar novas tabelas, vistas nem vistas materializadas num conjunto de dados externo do Spanner.
  • As INFORMATION_SCHEMA visualizações não são suportadas.
  • O armazenamento em cache de metadados não é suportado.
  • As definições ao nível do conjunto de dados relacionadas com as predefinições de criação de tabelas não afetam os conjuntos de dados externos porque não pode criar tabelas manualmente.
  • A API Write e a API Read não são suportadas.
  • A segurança ao nível da linha, a segurança ao nível da coluna e a ocultação de dados não são suportadas.
  • As vistas materializadas baseadas em tabelas de conjuntos de dados externos do Spanner não são suportadas.
  • A integração com o catálogo universal do Dataplex não é suportada. Por exemplo, os perfis de dados e as análises de qualidade dos dados não são suportados.
  • As etiquetas ao nível da tabela não são suportadas.
  • O preenchimento automático de SQL não funciona com tabelas externas do Spanner quando escreve consultas.
  • A análise com a Proteção de dados confidenciais não é suportada para conjuntos de dados externos.
  • A partilha com a partilha do BigQuery (anteriormente Analytics Hub) não é suportada para conjuntos de dados externos.
  • Se o conjunto de dados externo do Spanner usar credenciais do utilizador final (EUC), pode criar uma vista autorizada que faça referência ao conjunto de dados externo. No entanto, quando esta vista é consultada, o EUC de uma pessoa que executa uma consulta é enviado para o Spanner.
  • Se o conjunto de dados externo do Spanner usar uma ligação de recursos da nuvem para delegação de acesso, pode criar uma vista autorizada ou uma rotina autorizada que faça referência ao conjunto de dados externo.

O que se segue?