Criar conjuntos de dados externos do Spanner

Console

1. Acessar a página do BigQuery.

   Acessar o BigQuery

2. No painel à esquerda, clique em explore Explorer:

   

   Se o painel esquerdo não aparecer, clique em last_page Expandir painel esquerdo para abrir.

3. No painel Explorer, expanda o nome do projeto e clique em Conexões.

4. Na página Conexões, clique em Criar conexão.

5. Em Tipo de conexão, escolha Modelos remotos da Vertex AI, funções remotas, BigLake e Spanner (recurso do Cloud).

6. No campo ID da conexão, insira um nome para a conexão.

7. Em Tipo de local, selecione um local para a conexão. A conexão precisa estar no mesmo local que os outros recursos, como conjuntos de dados.

8. Clique em Criar conexão.

9. Clique em Ir para conexão.

10. No painel Informações da conexão, copie o ID da conta de serviço para uso em uma etapa posterior.

SQL

Use a instrução CREATE CONNECTION:

1. No console do Cloud de Confiance , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME`
   OPTIONS (
     connection_type = "CLOUD_RESOURCE",
     friendly_name = "FRIENDLY_NAME",
     description = "DESCRIPTION"
     );

   Substitua:

   • CONNECTION_NAME: o nome da conexão no formato PROJECT_ID.LOCATION.CONNECTION_ID, LOCATION.CONNECTION_ID ou CONNECTION_ID. Se o projeto ou o local forem omitidos, eles serão inferidos do projeto e do local em que a instrução é executada.
   • FRIENDLY_NAME (opcional): um nome descritivo para a conexão.
   • DESCRIPTION (opcional): uma descrição da conexão.

3. Clique em play_circle Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

1. Em um ambiente de linha de comando, crie uma conexão:

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID

   O parâmetro --project_id substitui o projeto padrão.

   Substitua:

   • REGION: sua região de conexão
   • PROJECT_ID: o ID do projeto do Cloud de Confiance .
   • CONNECTION_ID: um ID para sua conexão

   Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.

   Solução de problemas: se você receber o seguinte erro de conexão, atualize o SDK Google Cloud:

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. Recupere e copie o ID da conta de serviço para uso em uma etapa posterior:

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID

   O resultado será o seguinte:

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.s3ns-system.iam.gserviceaccount.com"}
   

Python

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Java

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.connection.v1.CloudResourceProperties;
import com.google.cloud.bigquery.connection.v1.Connection;
import com.google.cloud.bigquery.connection.v1.CreateConnectionRequest;
import com.google.cloud.bigquery.connection.v1.LocationName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import java.io.IOException;

public class CreateConnection {

  /**
   * Creates a BigQuery connection to a Cloud Resource. A Cloud Resource connection provisions a
   * service account that can be granted access to other Google Cloud resources for federated
   * queries.
   *
   * @param projectId The Google Cloud project ID (for example, "example-project-id").
   * @param location The geographic location of the connection (for example, "us-central1").
   * @param connectionId The ID of the connection to create (for example, "example-connection-id").
   */
  public static void createConnection(String projectId, String location, String connectionId) {
    LocationName parent = LocationName.of(projectId, location);

    // CloudResourceProperties provisions a managed Google Cloud service account on creation.
    CloudResourceProperties cloudResourceProperties = CloudResourceProperties.newBuilder().build();
    Connection connection =
        Connection.newBuilder()
            .setFriendlyName("Example Connection")
            .setDescription("Cloud Resource connection for federated queries.")
            .setCloudResource(cloudResourceProperties)
            .build();

    CreateConnectionRequest request =
        CreateConnectionRequest.newBuilder()
            .setParent(parent.toString())
            .setConnectionId(connectionId)
            .setConnection(connection)
            .build();

    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      Connection response = client.createConnection(request);

      System.out.printf("Successfully created connection: %s%n", response.getName());
      System.out.printf("Friendly name: %s%n", response.getFriendlyName());
      System.out.printf(
          "Service Account: %s%n", response.getCloudResource().getServiceAccountId());
    } catch (AlreadyExistsException err) {
      System.err.printf(
          "error: connection '%s' already exists in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    } catch (ApiException | IOException err) {
      System.err.printf(
          "error: failed to create connection '%s' in location '%s' for project '%s': %s%n",
          connectionId, location, projectId, err.getMessage());
    }
  }

Terraform

Use o recurso google_bigquery_connection.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

O exemplo a seguir cria uma conexão a recursos do Cloud chamada my_cloud_resource_connection na região US:

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Para aplicar a configuração do Terraform em um projeto do Cloud de Confiance , conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto padrão do Cloud de Confiance em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

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

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

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

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu projeto do Cloud de Confiance para ver os resultados. No console do Cloud de Confiance , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

Console

1. Abra a página do BigQuery no console do Cloud de Confiance .

   Acessar a página do BigQuery

2. No painel à esquerda, clique em explore Explorer:

   

   Se o painel esquerdo não aparecer, clique em last_page Expandir painel esquerdo para abrir.

3. No painel Explorador, selecione o projeto em que você quer criar o conjunto de dados.

4. Clique em more_vert Acessar ações e depois em Criar conjunto de dados.

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

   • Em Código do conjunto de dados, digite um nome exclusivo.
   • Em Tipo de local, escolha um local para o conjunto de dados, como us-central1 ou multirregião us. Depois que você cria um conjunto de dados, o local não pode ser alterado.

   • Em Conjunto de dados externo, faça o seguinte:

     • Marque a caixa ao lado de Vincular a um conjunto de dados externo.
     • Em Tipo de conjunto de dados externo, selecione Spanner.
     • Em Origem externa, insira o identificador completo do banco 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.
     • Opcional: em Papel do banco de dados, insira o nome de um papel do banco de dados do Spanner. Para mais informações, leia sobre os papéis de banco de dados usados para criar conexões do Spanner.
     • Se quiser, marque a caixa ao lado de Usar uma conexão a recursos do Cloud para criar o conjunto de dados externo com uma conexão.

   • Não altere as outras configurações.

6. Clique em Criar conjunto de dados.

SQL

Use a instrução de linguagem de definição de dados (DDL) CREATE EXTERNAL SCHEMA:

1. No console do Cloud de Confiance , acesse a página BigQuery.

   Acessar o BigQuery

2. No editor de consultas, digite a seguinte instruçã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:

   • DATASET_NAME: o nome do novo conjunto de dados no BigQuery.
   • SPANNER_EXTERNAL_SOURCE: o nome completo e qualificado do banco 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: o local do novo conjunto de dados no BigQuery, por exemplo, us-central1. Depois de criar um conjunto de dados, não será possível alterar o local dele.
   • (Opcional) CONNECTION_NAME: o nome da conexão a recursos do Cloud.

3. Clique em play_circle Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Em um ambiente de linha de comando, crie um conjunto de dados externo usando o comando bq mk:

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

Como alternativa, crie com uma conexão:

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

Substitua:

• LOCATION: o local do novo conjunto de dados no BigQuery. Por exemplo, us-central1. Depois de criar um conjunto de dados, não será possível alterar o local dele. É possível definir um valor de local padrão usando o arquivo .bigqueryrc.
• SPANNER_EXTERNAL_SOURCE: o nome completo e qualificado do banco 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 em um projeto diferente do projeto padrão, adicione a ID do projeto ao nome do conjunto de dados no seguinte formato: PROJECT_ID:DATASET_NAME.
• (Opcional) CONNECTION_NAME: o nome da conexão a recursos do Cloud.

Terraform

Use o recurso google_bigquery_dataset.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

O exemplo a seguir 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 em um projeto do Cloud de Confiance , conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

1. Inicie o Cloud Shell.

2. Defina o projeto padrão do Cloud de Confiance em que você quer aplicar as configurações do Terraform.

   Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

1. No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

   Copie o exemplo de código no main.tf recém-criado.

   Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.

3. Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
4. Salve as alterações.
5. Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.

   terraform init

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

   terraform init -upgrade

Aplique as alterações

1. Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:

   terraform plan

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

2. Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:

   terraform apply

   Aguarde até que o Terraform exiba a mensagem "Apply complete!".

3. Abra seu projeto do Cloud de Confiance para ver os resultados. No console do Cloud de Confiance , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

API

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