Vista geral da associação predefinida

Para simplificar o seu fluxo de trabalho, pode configurar uma associação de recursos da Cloud predefinida no BigQuery para criar tabelas externas e modelos remotos do BigQuery ML. Um administrador configura a associação predefinida e, em seguida, os utilizadores podem referenciá-la durante a criação de recursos em vez de terem de especificar os detalhes da associação.

O BigQuery suporta associações predefinidas nos seguintes recursos:

Para usar a associação predefinida, especifique a palavra-chave DEFAULT nas seguintes cláusulas SQL:

Antes de começar

Enable the BigQuery Connection API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Funções e autorizações necessárias

Para trabalhar com associações predefinidas, use as seguintes funções de gestão de identidade e de acesso (IAM):

  • Usar a associação predefinida: utilizador da associação do BigQuery (roles/bigquery.connectionUser) no seu projeto
  • Defina a associação predefinida: administrador do BigQuery (roles/bigquery.admin) no seu projeto

  • Se for necessário conceder autorizações à conta de serviço de uma associação predefinida:

    • Se a ligação predefinida for usada para criar tabelas externas: Storage Admin (roles/storage.admin) em quaisquer contentores do Cloud Storage usados pelas tabelas externas.

    • Se a ligação predefinida for usada para criar modelos remotos: Project IAM Admin (roles/resourcemanager.projectIamAdmin) no projeto que contém o ponto final do Vertex AI. Para os seguintes tipos de modelos remotos, este é o projeto atual:

      • Modelos remotos através dos serviços de IA na nuvem.
      • Modelos remotos sobre modelos da Google ou de parceiros que criou ao especificar o nome do modelo como um ponto final.

      Para todos os outros modelos remotos, este é o projeto que contém o endpoint do Vertex AI no qual o modelo de destino está implementado.

      Se usar o modelo remoto para analisar dados não estruturados de uma tabela de objetos e o contentor do Cloud Storage que usa na tabela de objetos estiver num projeto diferente do seu ponto final do Vertex AI, também tem de ter a função de administrador de armazenamento (roles/storage.admin) no contentor do Cloud Storage usado pela tabela de objetos.

    Só precisa destas funções se for um administrador a configurar uma ligação para utilização como ligação predefinida ou um utilizador que esteja a usar uma ligação predefinida à qual ainda não foi concedida a função adequada à respetiva conta de serviço. Para mais informações, consulte o artigo Configure a associação predefinida.

Estas funções predefinidas contêm as autorizações necessárias para realizar as tarefas descritas neste documento. Para ver as autorizações exatas necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

  • Usar a ligação predefinida: bigquery.connections.use
  • Crie uma associação: bigquery.connections.*
  • Defina a ligação predefinida: bigquery.config.*
  • Defina autorizações de contas de serviço para uma associação predefinida que é usada para criar tabelas externas: storage.buckets.getIamPolicy e storage.buckets.setIamPolicy
  • Defina autorizações da conta de serviço para uma associação predefinida que é usada para criar modelos remotos:
    • resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
    • Se a ligação predefinida for usada com um modelo remoto que processa dados não estruturados de uma tabela de objetos, storage.buckets.getIamPolicy e storage.buckets.setIamPolicy

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

Configure a ligação predefinida

Para configurar a ligação predefinida pela primeira vez, use um dos seguintes métodos:

  • Crie uma associação, conceda funções adequadas à conta de serviço da associação e, de seguida, defina a associação como a associação predefinida.

    O utilizador que cria e configura a associação predefinida precisa da função de administrador do BigQuery e da função de administrador do armazenamento ou administrador do IAM do projeto, conforme adequado. O utilizador da ligação predefinida precisa da função de utilizador da ligação do BigQuery.

  • Crie uma associação e, em seguida, defina-a como a associação predefinida. O serviço concede as funções adequadas à conta de serviço da ligação predefinida quando esta é usada.

    O utilizador que cria e define a ligação predefinida precisa da função de administrador do BigQuery. O utilizador da ligação predefinida precisa da função de utilizador da ligação do BigQuery e da função de administrador do armazenamento ou administrador de IAM do projeto, conforme adequado.

  • Especifique a palavra-chave DEFAULT numa declaração suportada. O serviço cria uma associação, concede funções adequadas à conta de serviço da associação e, em seguida, define a associação como a associação predefinida.

    O utilizador da ligação predefinida precisa da função de administrador do BigQuery e da função de administrador do Storage ou de administrador do IAM do projeto, conforme adequado.

Defina a associação predefinida para um projeto

Defina a ligação de recursos da nuvem predefinida para o projeto através da declaração DDL ALTER PROJECT SET OPTIONS.

O exemplo seguinte define a associação predefinida para o projeto:

  ALTER PROJECT PROJECT_ID
  SET OPTIONS (
    `region-REGION.default_cloud_resource_connection_id` = CONNECTION_ID);

Substitua o seguinte:

  • PROJECT_ID: o ID do projeto onde está a definir a associação predefinida.
  • REGION: a região da ligação.
  • CONNECTION_ID: o ID ou o nome da associação a usar como predefinição para tabelas e modelos. Especifique apenas o ID ou o nome da ligação e exclua os prefixos do ID do projeto e da região anexados ao nome ou ao ID.

Para mais informações sobre como configurar uma associação predefinida para um projeto, consulte o artigo Faça a gestão das configurações predefinidas.

Aprovisionamento de autorizações para a ligação predefinida

Quando usa a ligação predefinida para criar uma tabela externa ou um modelo remoto, Google Cloud concede à conta de serviço da ligação predefinida as funções adequadas se a conta de serviço ainda não as tiver. Esta ação falha se não tiver privilégios administrativos no Cloud Storage ou no recurso do Vertex AI usado pela tabela externa ou pelo modelo remoto.

As seguintes funções são concedidas à conta de serviço da associação predefinida:

Tipo de tabela ou modelo Recurso remoto Funções atribuídas à conta de serviço da associação
Tabela do Cloud Storage BigLake Cloud Storage roles/storage.legacyBucketReader
roles/storage.legacyObjectReader
Tabela de objetos Cloud Storage roles/storage.legacyBucketReader
roles/storage.legacyObjectReader
Tabelas Iceberg do BigLake no BigQuery Cloud Storage roles/storage.legacyBucketWriter
roles/storage.legacyObjectOwner
Modelos remotos do BigQuery ML sobre modelos da Vertex AI Modelos da Google roles/aiplatform.user
Implementável num ponto final a partir do Model Garden
Modelos de utilizadores
Modelos otimizados roles/aiplatform.serviceAgent
Modelos remotos do BigQuery ML sobre os serviços de IA da nuvem Processador de documentos roles/documentai.apiUser
Reconhecimento de voz roles/speech.serviceAgent
PLN do Cloud roles/serviceusage.serviceUsageConsumer
Cloud Vision roles/serviceusage.serviceUsageConsumer
Cloud Translation roles/cloudtranslate.user

Crie tabelas externas com CONNECTION DEFAULT

Os exemplos seguintes mostram como criar tabelas externas especificando WITH CONNECTION DEFAULT no BigQuery.

Exemplo: crie uma tabela do BigLake do Cloud Storage

A seguinte expressão SQL cria uma tabela do BigLake do Cloud Storage com uma associação predefinida:

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  format = 'TABLE_FORMAT',
  uris = ['BUCKET_PATH']);

Exemplo: crie uma tabela de objetos com uma associação predefinida

A seguinte expressão SQL cria uma tabela de objetos com uma associação predefinida:

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  object_metadata = 'SIMPLE'
  uris = ['BUCKET_PATH']);

Exemplo: crie tabelas Iceberg do BigLake no BigQuery com uma ligação predefinida

A seguinte expressão SQL cria tabelas Iceberg do BigLake no BigQuery com uma associação predefinida:

CREATE TABLE `myproject.tpch_clustered.nation` (
  n_nationkey integer,
  n_name string,
  n_regionkey integer,
  n_comment string)
CLUSTER BY n_nationkey
WITH CONNECTION DEFAULT
OPTIONS (
  file_format = 'PARQUET',
  table_format = 'ICEBERG',
  storage_uri = 'gs://mybucket/warehouse/nation');

Crie modelos remotos com o REMOTE WITH CONNECTION DEFAULT

Os exemplos seguintes mostram como criar modelos remotos especificando REMOTE WITH CONNECTION DEFAULT no BigQuery.

Exemplo: crie um modelo remoto sobre um modelo do Vertex AI

A seguinte expressão SQL cria um modelo remoto com uma associação predefinida:

CREATE OR REPLACE MODEL `mydataset.flash_model`
  REMOTE WITH CONNECTION DEFAULT
  OPTIONS(ENDPOINT = 'gemini-2.0-flash');

Exemplo: crie um modelo remoto através de um serviço de IA na nuvem

A seguinte expressão SQL cria um modelo remoto num serviço de IA na nuvem com uma ligação predefinida:

CREATE MODEL `project_id.mydataset.mymodel`
REMOTE WITH CONNECTION DEFAULT
 OPTIONS(REMOTE_SERVICE_TYPE = 'CLOUD_AI_VISION_V1')

Exemplo: crie um modelo remoto com um ponto final HTTPS

A seguinte expressão SQL cria um modelo remoto com um ponto final HTTPS e uma ligação predefinida:

CREATE MODEL `project_id.mydataset.mymodel`
 INPUT(f1 INT64, f2 FLOAT64, f3 STRING, f4 ARRAY)
 OUTPUT(out1 INT64, out2 INT64)
 REMOTE WITH CONNECTION DEFAULT
 OPTIONS(ENDPOINT = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234')

O que se segue?