Questa pagina è stata tradotta dall'API Cloud Translation.

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, che gli utenti possono poi utilizzare come riferimento durante la creazione delle risorse anziché dover specificare i dettagli di connessione.

BigQuery supporta le connessioni predefinite nelle seguenti risorse:

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 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 autorizzazioni all'account di servizio di una connessione predefinita:
- Se per creare le tabelle esterne viene utilizzata la connessione predefinita: 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 del progetto (roles/resourcemanager.projectIamAdmin) nel progetto che contiene l'endpoint Vertex AI. Per i seguenti tipi di modelli remoti, si tratta del progetto corrente:
  - Modelli remoti tramite i servizi Cloud AI.
  - Modelli remoti su Google o modelli di partner che hai creato specificando il nome del modello come endpoint.
  Per tutti gli altri modelli remoti, si tratta del progetto che contiene l'endpoint Vertex AI a cui è di destinazione il modello.
  
  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 dall'endpoint Vertex AI, devi disporre anche del ruolo Amministratore archiviazione (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 è stato ancora concesso il ruolo appropriato al suo 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 dell'account di servizio per una connessione predefinita utilizzata per creare tabelle esterne: storage.buckets.getIamPolicy e storage.buckets.setIamPolicy
Imposta le autorizzazioni dell'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 all'account di servizio della connessione e impostala 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 predefinito 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 IAM del progetto o Amministratore archiviazione, 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 IAM del progetto o dello spazio di archiviazione, a seconda dei casi.

Impostare la connessione predefinita per un progetto

Imposta la connessione alla risorsa 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 l'ID progetto e i prefissi della regione associati al nome o all'ID.

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

Provision delle autorizzazioni per la connessione predefinita

Quando utilizzi la connessione predefinita per creare una tabella esterna o un modello remoto, Google Cloud concede all'account di servizio della connessione predefinita i ruoli appropriati, se 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.

I seguenti ruoli vengono concessi all'account di servizio della connessione predefinita:

Tipo di tabella o modello	Risorsa remota	Ruoli assegnati all'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 BigLake Iceberg in BigQuery	Cloud Storage	`roles/storage.legacyBucketWriter` `roles/storage.legacyObjectOwner`
Modelli BigQuery ML remoti rispetto ai modelli Vertex AI	Modelli di proprietà di Google	`roles/aiplatform.user`
	Disponibile per il deployment in un endpoint da Model Garden
	Modelli utente
	Modelli ottimizzati	`roles/aiplatform.serviceAgent`
Modelli BigQuery ML remoti tramite i servizi Cloud AI	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`

Gli esempi riportati di seguito 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 BigLake Iceberg in BigQuery con una connessione predefinita

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

Creare 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 in 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.