Panoramica della connessione predefinita

Una connessione alle risorse Cloud predefinita in BigQuery ti consente di creare tabelle esterne e modelli remoti BigQuery ML senza specificare i dettagli della singola connessione o gestire ogni volta le autorizzazioni del account di servizio. Dopo aver configurato una connessione predefinita per un progetto, gli utenti possono farvi riferimento specificando la parola chiave DEFAULT nelle istruzioni SQL.

Risorse e clausole SQL supportate

BigQuery supporta le connessioni predefinite nelle seguenti risorse:

• Tabelle BigLake di Cloud Storage
• Tabelle di oggetti
• Tabelle gestite Apache Iceberg
• Modelli di telecomando

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

• La clausola WITH CONNECTION di un'istruzione CREATE EXTERNAL TABLE
• La clausola REMOTE WITH CONNECTION di un'istruzione CREATE MODEL per un modello remoto

Prima di iniziare

Abilita l'API BigQuery Connection, se non è già abilitata.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilitare l'API

Ruoli e autorizzazioni richiesti

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

• Utilizza la connessione predefinita: BigQuery Connection User (roles/bigquery.connectionUser) nel tuo progetto
• Imposta la connessione predefinita: Amministratore connessione BigQuery (roles/bigquery.connectionAdmin) sul tuo progetto

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

  • Se la connessione predefinita viene utilizzata per creare tabelle esterne: Storage Admin (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) sul progetto che contiene l'endpoint di Gemini Enterprise Agent Platform. Per i seguenti tipi di modelli remoti, questo è il progetto corrente:

    • 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 Agent Platform in cui è stato eseguito il deployment del modello di destinazione.

    Se utilizzi il modello remoto per analizzare i dati non strutturati di una tabella di oggetti e il bucket Cloud Storage che utilizzi nella tabella di oggetti si trova in un progetto diverso da quello dell'endpoint della piattaforma agente, devi disporre anche del ruolo Storage Admin (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 per il account di servizio. Per saperne di più, consulta Configura la connessione predefinita.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per eseguire le attività descritte in questo documento. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

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.

Configura 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 imposta la connessione come predefinita.

  L'utente che crea e configura la connessione predefinita deve disporre del ruolo BigQuery Admin e del ruolo Storage Admin o Project IAM Admin, a seconda dei casi. L'utente della connessione predefinita deve avere il ruolo BigQuery Connection User.

• Crea una connessione e 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 avere il ruolo Amministratore BigQuery. L'utente della connessione predefinita deve disporre del ruolo BigQuery Connection User e del ruolo Storage Admin o Project IAM Admin, 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 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.

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

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

Importante: l'utilizzo di una connessione predefinita può estendere privilegi aggiuntivi agli utenti. Ad esempio, se un amministratore utilizza la connessione predefinita per creare una tabella di oggetti, al account di servizio della connessione predefinita vengono concessi i ruoli Storage Legacy Bucket Reader e Storage Legacy Object Reader sul bucket Cloud Storage appropriato. Qualsiasi utente a cui è stato concesso l'accesso per utilizzare la connessione può quindi accedere anche al bucket Cloud Storage con le autorizzazioni concesse a questi ruoli.

Imposta la connessione predefinita per un progetto

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

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 associati al nome o all'ID.

Per saperne di più sulla configurazione di una connessione predefinita per un progetto, consulta Gestisci 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 Agent Platform 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 degli oggetti	Cloud Storage	roles/storage.legacyBucketReader roles/storage.legacyObjectReader
Tabelle gestite Iceberg	Cloud Storage	roles/storage.legacyBucketWriter roles/storage.legacyObjectOwner
Modelli remoti di BigQuery ML sui modelli di Gemini Enterprise Agent Platform	Modelli di proprietà di Google	roles/aiplatform.user
	Deployment su 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

Crea tabelle esterne utilizzando CONNECTION DEFAULT

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

Esempio: crea 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: crea 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: crea tabelle gestite Iceberg con una connessione predefinita

La seguente espressione SQL crea una tabella gestita 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');

Crea modelli remoti utilizzando REMOTE WITH CONNECTION DEFAULT

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

Esempio: crea un modello remoto su un modello Agent Platform

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: crea 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: crea 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

• Scopri di più sulla configurazione predefinita in BigQuery.