Panoramica della connessione predefinita

Per semplificare il workflow, puoi configurare una connessione predefinita alle risorse Cloud in BigQuery per la creazione di tabelle esterne e modelli remoti BigQuery ML. Un amministratore configura la connessione predefinita, quindi gli utenti possono farvi riferimento durante la creazione delle risorse anziché dover specificare i dettagli della connessione.

BigQuery supporta le connessioni predefinite nelle seguenti risorse:

Per utilizzare la connessione predefinita, specifica la parola chiave DEFAULT nelle seguenti clausole SQL:

Prima di iniziare

Abilita l'API BigQuery Connection.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilitare l'API

Ruoli e autorizzazioni richiesti

Per utilizzare le connessioni predefinite, utilizza i seguenti ruoli IAM (Identity and Access Management):

  • Utilizza la connessione predefinita: Utente connessione BigQuery (roles/bigquery.connectionUser) nel tuo progetto
  • Imposta la connessione predefinita: Amministratore BigQuery (roles/bigquery.admin) nel tuo progetto

  • Se è necessario concedere le autorizzazioni al account di servizio di una connessione predefinita:

    • Se la connessione predefinita viene utilizzata per creare tabelle esterne: Amministratore Storage (roles/storage.admin) su tutti i bucket Cloud Storage utilizzati dalle tabelle esterne.

    • Se la connessione predefinita viene utilizzata per creare modelli remoti: Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) nel progetto che contiene l'endpoint Vertex AI. Per i seguenti tipi di modelli remoti, questo è il progetto attuale:

      • Modelli remoti sui servizi AI Cloud.
      • Modelli remoti su modelli Google o partner che hai creato specificando il nome del modello come endpoint.

      Per tutti gli altri modelli remoti, questo è il progetto che contiene l'endpoint Vertex AI su cui viene eseguito il deployment del modello di destinazione.

      Se utilizzi il modello remoto per analizzare i dati non strutturati da una tabella di oggetti e il bucket Cloud Storage utilizzato nella tabella di oggetti si trova in un progetto diverso dall'endpoint Vertex AI, devi disporre anche del ruolo Amministratore Storage (roles/storage.admin) sul bucket Cloud Storage utilizzato dalla tabella di oggetti.

    Questi ruoli sono necessari solo se sei un amministratore che configura una connessione da utilizzare come connessione predefinita o un utente che utilizza una connessione predefinita a cui non è ancora stato concesso il ruolo appropriato al relativo account di servizio. Per ulteriori informazioni, consulta Configurare la connessione predefinita.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per eseguire le attività descritte in questo documento. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

  • Utilizza la connessione predefinita: bigquery.connections.use
  • Crea una connessione: bigquery.connections.*
  • Imposta la connessione predefinita: bigquery.config.*
  • Imposta le autorizzazioni del account di servizio per una connessione predefinita utilizzata per creare tabelle esterne: storage.buckets.getIamPolicy e storage.buckets.setIamPolicy
  • Imposta le autorizzazioni del account di servizio per una connessione predefinita utilizzata per creare modelli remoti:
    • resourcemanager.projects.getIamPolicy e resourcemanager.projects.setIamPolicy
    • Se la connessione predefinita viene utilizzata con un modello remoto che elabora dati non strutturati da una tabella di oggetti, storage.buckets.getIamPolicy e storage.buckets.setIamPolicy

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Configurare la connessione predefinita

Per configurare la connessione predefinita per la prima volta, utilizza uno dei seguenti metodi:

  • Crea una connessione, concedi i ruoli appropriati al service account della connessione e poi imposta la connessione come predefinita.

    L'utente che crea e configura la connessione predefinita deve disporre del ruolo Amministratore BigQuery e del ruolo Amministratore Storage o Amministratore IAM progetto, a seconda dei casi. L'utente della connessione predefinita deve disporre del ruolo Utente connessione BigQuery.

  • Crea una connessione e poi impostala come predefinita. Il servizio concede i ruoli appropriati al account di servizio della connessione predefinita quando viene utilizzata la connessione predefinita.

    L'utente che crea e imposta la connessione predefinita deve disporre del ruolo Amministratore BigQuery. L'utente della connessione predefinita deve disporre del ruolo Utente connessione BigQuery e del ruolo Amministratore Storage o Amministratore IAM progetto, a seconda dei casi.

  • Specifica la parola chiave DEFAULT in un'istruzione supportata. Il servizio crea una connessione, concede i ruoli appropriati al service account della connessione e poi imposta la connessione come predefinita.

    L'utente della connessione predefinita deve disporre del ruolo Amministratore BigQuery e del ruolo Amministratore Storage o Amministratore IAM progetto, a seconda dei casi.

  • Quando la connessione predefinita non è presente, BigQuery crea una nuova connessione con le seguenti proprietà:

    • Regione: la stessa regione del set di dati.
    • Nome: __default_cloudresource_connection__
    • Tipo: CLOUD_RESOURCE

Impostare la connessione predefinita per un progetto

Imposta la connessione predefinita alle risorse Cloud per il progetto utilizzando l' ALTER PROJECT SET OPTIONS istruzione DDL.

L'esempio seguente imposta la connessione predefinita per il progetto:

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

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto in cui stai impostando la connessione predefinita.
  • REGION: la regione della connessione.
  • CONNECTION_ID: l'ID o il nome della connessione da utilizzare come predefinita per tabelle e modelli. Specifica solo l'ID o il nome della connessione ed escludi i prefissi dell'ID progetto e della regione allegati al nome o all'ID.

Per ulteriori informazioni sulla configurazione di una connessione predefinita per un progetto, consulta Gestire le configurazioni predefinite.

Provisioning delle autorizzazioni per la connessione predefinita

Quando utilizzi la connessione predefinita per creare una tabella esterna o un modello remoto, Google Cloud concede al account di servizio della connessione predefinita i ruoli appropriati se il account di servizio non li ha già. Questa azione non riesce se non disponi dei privilegi amministrativi sulla risorsa Cloud Storage o Vertex AI utilizzata dalla tabella esterna o dal modello remoto.

Al account di servizio della connessione predefinita vengono concessi i seguenti ruoli:

Tipo di tabella o modello Risorsa remota Ruoli assegnati al account di servizio della connessione
Tabella BigLake di Cloud Storage Cloud Storage roles/storage.legacyBucketReader
roles/storage.legacyObjectReader
Tabella di oggetti Cloud Storage roles/storage.legacyBucketReader
roles/storage.legacyObjectReader
Tabelle gestite Iceberg Cloud Storage roles/storage.legacyBucketWriter
roles/storage.legacyObjectOwner
Modelli remoti BigQuery ML sui modelli Vertex AI Modelli di proprietà di Google roles/aiplatform.user
Eseguibili il deployment in un endpoint da Model Garden
Modelli utente
Modelli ottimizzati roles/aiplatform.serviceAgent
Modelli remoti BigQuery ML sui servizi AI Cloud Processore di documenti roles/documentai.apiUser
Riconoscimento vocale roles/speech.serviceAgent
Cloud NLP roles/serviceusage.serviceUsageConsumer
Cloud Vision roles/serviceusage.serviceUsageConsumer
Cloud Translation roles/cloudtranslate.user

Creare tabelle esterne utilizzando CONNECTION DEFAULT

I seguenti esempi mostrano come creare tabelle esterne specificando WITH CONNECTION DEFAULT in BigQuery.

Esempio: creare una tabella BigLake di Cloud Storage

La seguente espressione SQL crea una tabella BigLake di Cloud Storage con una connessione predefinita:

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

Esempio: creare una tabella di oggetti con una connessione predefinita

La seguente espressione SQL crea una tabella di oggetti con una connessione predefinita:

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

Esempio: creare tabelle gestite Iceberg con una connessione predefinita

La seguente espressione SQL crea tabelle gestite Iceberg con una connessione predefinita:

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');

Creare modelli remoti utilizzando REMOTE WITH CONNECTION DEFAULT

I seguenti esempi mostrano come creare modelli remoti specificando REMOTE WITH CONNECTION DEFAULT in BigQuery.

Esempio: creare un modello remoto su un modello Vertex AI

La seguente espressione SQL crea un modello remoto con una connessione predefinita:

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

Esempio: creare un modello remoto su un servizio AI Cloud

La seguente espressione SQL crea un modello remoto su un servizio AI Cloud con una connessione predefinita:

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

Esempio: creare un modello remoto con un endpoint HTTPS

La seguente espressione SQL crea un modello remoto con un endpoint HTTPS e una connessione predefinita:

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

Passaggi successivi