Panoramica della connessione predefinita

Per semplificare il flusso di lavoro, puoi configurare una connessione alle risorse Cloud predefinita in BigQuery per creare 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:

• Tabelle BigLake di Cloud Storage
• Tabelle di oggetti
• Tabelle BigLake per Apache Iceberg in BigQuery
• 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

Enable the BigQuery Connection API.

Enable the API

Ruoli e autorizzazioni richiesti

Per lavorare con 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: BigQuery Admin (roles/bigquery.admin) nel 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) nel progetto che contiene l'endpoint Vertex AI. Per i seguenti tipi di modelli remoti, questo è il progetto attuale:

    • Modelli remoti tramite i servizi Cloud AI.
    • Modelli remoti su Google o modelli partner creati specificando il nome del modello come endpoint.

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

    Se utilizzi il modello remoto per analizzare dati non strutturati da una tabella di oggetti e il bucket Cloud Storage che utilizzi nella tabella di oggetti si trova in un progetto diverso dall'endpoint Vertex AI, devi disporre anche del ruolo Amministratore Storage (roles/storage.admin) nel 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 relativo account di servizio. Per ulteriori informazioni, vedi Configurare 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:

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 BigQuery Admin e del ruolo Storage Admin o Project IAM Admin, a seconda dei casi. L'utente della connessione predefinita deve disporre del ruolo Utente connessione BigQuery.

• Crea una connessione e impostala come predefinita. Il servizio concede i ruoli appropriati all'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 BigQuery Admin. L'utente di connessione predefinito 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 all'account di servizio della connessione e poi imposta la connessione come predefinita.

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

Impostare la connessione predefinita per un progetto

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

Il seguente esempio 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 ID progetto e regione allegati al nome o all'ID.

Per saperne di più sulla configurazione di una connessione predefinita per un progetto, vedi 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, Trusted Cloud by S3NS concede all'account di servizio della connessione predefinita i ruoli appropriati se l'account di servizio non li ha già. Questa azione non va a buon fine 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:

Creare tabelle esterne utilizzando CONNECTION DEFAULT

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

Esempio: crea una tabella BigLake 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 degli oggetti con una connessione predefinita

La seguente espressione SQL crea una tabella degli 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 BigLake Iceberg in BigQuery con una connessione predefinita

La seguente espressione SQL crea tabelle BigLake Iceberg in BigQuery 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 riportati di seguito mostrano come creare modelli remoti specificando REMOTE WITH CONNECTION DEFAULT in BigQuery.

Esempio: crea 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: crea un modello remoto su un servizio Cloud AI

La seguente espressione SQL crea un modello remoto su un servizio Cloud AI 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.