Présentation de la connexion par défaut

Pour simplifier votre workflow, vous pouvez configurer une connexion à une ressource cloud par défaut dans BigQuery pour créer des tables externes et des modèles distants BigQuery ML. Un administrateur configure la connexion par défaut, puis les utilisateurs peuvent y faire référence lors de la création de ressources au lieu d'avoir à spécifier les détails de la connexion.

BigQuery est compatible avec les connexions par défaut dans les ressources suivantes :

• Tables BigLake Cloud Storage
• Tables d'objets
• Tables BigLake pour Apache Iceberg dans BigQuery
• Modèles distants

Pour utiliser la connexion par défaut, spécifiez le mot clé DEFAULT dans les clauses SQL suivantes :

• Clause WITH CONNECTION d'une instruction CREATE EXTERNAL TABLE
• Clause REMOTE WITH CONNECTION d'une instruction CREATE MODEL pour un modèle distant

Avant de commencer

Enable the BigQuery Connection API.

Enable the API

Rôles et autorisations requis

Pour utiliser les connexions par défaut, utilisez les rôles IAM (Identity and Access Management) suivants :

• Utilisez la connexion par défaut : utilisateur de connexion BigQuery (roles/bigquery.connectionUser) sur votre projet.
• Définir la connexion par défaut : administrateur BigQuery (roles/bigquery.admin) sur votre projet

• Si vous devez accorder des autorisations au compte de service d'une connexion par défaut :

  • Si la connexion par défaut est utilisée pour créer des tables externes : rôle Administrateur de l'espace de stockage (roles/storage.admin) sur tous les buckets Cloud Storage utilisés par les tables externes.

  • Si la connexion par défaut est utilisée pour créer des modèles distants : administrateur IAM du projet (roles/resourcemanager.projectIamAdmin) sur le projet contenant le point de terminaison Vertex AI. Pour les types de modèles distants suivants, il s'agit du projet actuel :

    • Modèles distants sur les services Cloud AI.
    • Modèles distants sur des modèles Google ou partenaires que vous avez créés en spécifiant le nom du modèle en tant que point de terminaison.

    Pour tous les autres modèles distants, il s'agit du projet contenant le point de terminaison Vertex AI sur lequel le modèle cible est déployé.

    Si vous utilisez le modèle distant pour analyser des données non structurées à partir d'une table d'objets et que le bucket Cloud Storage que vous utilisez dans la table d'objets se trouve dans un projet différent de votre point de terminaison Vertex AI, vous devez également disposer du rôle Administrateur de l'espace de stockage (roles/storage.admin) sur le bucket Cloud Storage utilisé par la table d'objets.

  Vous n'avez besoin de ces rôles que si vous êtes un administrateur qui configure une connexion à utiliser comme connexion par défaut, ou un utilisateur qui utilise une connexion par défaut dont le compte de service n'a pas encore reçu le rôle approprié. Pour en savoir plus, consultez Configurer la connexion par défaut.

Ces rôles prédéfinis contiennent les autorisations requises pour effectuer les tâches décrites dans ce document. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Configurer la connexion par défaut

Pour configurer la connexion par défaut pour la première fois, utilisez l'une des méthodes suivantes :

• Créez une connexion, attribuez les rôles appropriés au compte de service de la connexion, puis définissez la connexion comme connexion par défaut.

  L'utilisateur qui crée et configure la connexion par défaut doit disposer du rôle Administrateur BigQuery et, selon le cas, du rôle Administrateur Storage ou Administrateur IAM du projet. L'utilisateur de connexion par défaut doit disposer du rôle "Utilisateur de connexion BigQuery".

• Créez une connexion, puis définissez-la comme connexion par défaut. Le service accorde les rôles appropriés au compte de service de la connexion par défaut lorsque celle-ci est utilisée.

  L'utilisateur qui crée et définit la connexion par défaut doit disposer du rôle Administrateur BigQuery. L'utilisateur de connexion par défaut doit disposer du rôle Utilisateur de connexion BigQuery et, le cas échéant, du rôle Administrateur Storage ou Administrateur IAM du projet.

• Spécifiez le mot clé DEFAULT dans une instruction acceptée. Le service crée une connexion, attribue les rôles appropriés au compte de service de la connexion, puis définit la connexion comme connexion par défaut.

  L'utilisateur de connexion par défaut doit disposer du rôle Administrateur BigQuery et du rôle Administrateur Storage ou Administrateur IAM du projet, selon le cas.

Définir la connexion par défaut pour un projet

Définissez la connexion de ressources Cloud par défaut pour le projet à l'aide de l'instruction LDD ALTER PROJECT SET OPTIONS.

L'exemple suivant définit la connexion par défaut pour le projet :

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

Remplacez les éléments suivants :

• PROJECT_ID : ID du projet dans lequel vous définissez la connexion par défaut.
• REGION : région de la connexion.
• CONNECTION_ID : ID ou nom de la connexion à utiliser par défaut pour les tables et les modèles. Indiquez uniquement l'ID ou le nom de la connexion, et excluez les préfixes d'ID de projet et de région associés au nom ou à l'ID.

Pour en savoir plus sur la configuration d'une connexion par défaut pour un projet, consultez Gérer les configurations par défaut.

Provisionnement des autorisations pour la connexion par défaut

Lorsque vous utilisez la connexion par défaut pour créer une table externe ou un modèle distant,Trusted Cloud by S3NS attribue au compte de service de la connexion par défaut les rôles appropriés si le compte de service ne les possède pas déjà. Cette action échoue si vous ne disposez pas de droits d'administrateur sur la ressource Cloud Storage ou Vertex AI utilisée par la table externe ou le modèle distant.

Les rôles suivants sont attribués au compte de service de la connexion par défaut :

Créer des tables externes à l'aide de CONNECTION DEFAULT

Les exemples suivants montrent comment créer des tables externes en spécifiant WITH CONNECTION DEFAULT dans BigQuery.

Exemple : Créer une table BigLake Cloud Storage

L'expression SQL suivante crée une table BigLake Cloud Storage avec une connexion par défaut :

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

Exemple : Créer une table d'objets avec une connexion par défaut

L'expression SQL suivante crée une table d'objets avec une connexion par défaut :

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

Exemple : Créer des tables BigLake Iceberg dans BigQuery avec une connexion par défaut

L'expression SQL suivante crée des tables BigLake Iceberg dans BigQuery avec une connexion par défaut :

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

Créer des modèles distants à l'aide de REMOTE WITH CONNECTION DEFAULT

Les exemples suivants montrent comment créer des modèles distants en spécifiant REMOTE WITH CONNECTION DEFAULT dans BigQuery.

Exemple : Créer un modèle distant sur un modèle Vertex AI

L'expression SQL suivante crée un modèle distant avec une connexion par défaut :

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

Exemple : Créer un modèle distant sur un service Cloud AI

L'expression SQL suivante crée un modèle distant sur un service Cloud AI avec une connexion par défaut :

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

Exemple : Créer un modèle distant avec un point de terminaison HTTPS

L'expression SQL suivante crée un modèle distant avec un point de terminaison HTTPS et une connexion par défaut :

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

Étapes suivantes

• En savoir plus sur la configuration par défaut dans BigQuery