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 s'y référer lors de la création de ressources au lieu d'avoir à spécifier les détails de la connexion.

BigQuery accepte 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:

• Utiliser la connexion par défaut: utilisateur de connexion BigQuery (roles/bigquery.connectionUser) sur votre projet
• Définissez 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: Storage Admin (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 en cours:

    • 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 qui contient le point de terminaison Vertex AI auquel le modèle cible est déployé.

    Si vous utilisez le modèle distant pour analyser les données non structurées 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 administrateur et que vous configurez une connexion à utiliser comme connexion par défaut, ou si vous êtes un utilisateur qui utilise une connexion par défaut à laquelle le rôle approprié n'a pas encore été attribué à son compte de service. Pour en savoir plus, consultez la section 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 du rôle Administrateur de stockage ou Administrateur IAM de projet, le cas échéant. 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 la connexion par défaut 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 du rôle "Storage Admin" ou "Project IAM Admin", le cas échéant.

• Spécifiez le mot clé DEFAULT dans une instruction compatible. 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 la connexion par défaut doit disposer du rôle "Administrateur BigQuery" et du rôle "Administrateur de stockage" ou "Administrateur IAM de projet", le cas échéant.

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 du 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. Spécifiez uniquement l'ID ou le nom de la connexion, et excluez les ID de projet et les préfixes 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 la section 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,Google Cloud accorde au compte de service de la connexion par défaut les rôles appropriés s'il ne les possède pas déjà. Cette action échoue si vous ne disposez pas d'autorisations administratives 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

• Découvrez la configuration par défaut dans BigQuery.