Se connecter à Spanner

En tant qu'administrateur BigQuery, vous pouvez créer une connexion permettant d'accéder aux données Spanner. Cette connexion permet aux analystes de données d'interroger des données dans Cloud Spanner.

Avant de commencer

Créer des connexions Spanner

Sélectionnez l'une des options suivantes :

Console

  1. Accédez à la page BigQuery.

    Accéder à BigQuery

  2. Dans le volet Explorateur, cliquez sur Ajouter, puis sélectionnez Connexions à la source de données externe.

  3. Dans le volet Source de données externes, saisissez les informations suivantes :

    • Dans le champ Type de connexion, sélectionnez Cloud Spanner.
    • Dans le champ Connection ID (ID de connexion), saisissez un identifiant pour la ressource de connexion. Les lettres, les chiffres et les traits de soulignement sont autorisés.
    • Pour Type d'emplacement, sélectionnez un emplacement (ou une région) BigQuery compatible avec votre région de source de données externe.
    • (Facultatif) Dans le champ Nom descriptif, saisissez un nom clair pour identifier la connexion, tel que My connection resource. Le nom descriptif peut être n'importe quelle valeur permettant d'identifier la ressource de connexion si vous devez la modifier par la suite.
    • Facultatif : Dans le champ Description, saisissez une description pour la ressource de connexion.
    • Dans le champ Nom de la base de données, saisissez le nom de la base de données Spanner au format suivant : "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE"
    • Facultatif : Pour effectuer des lectures parallèles, sélectionnez Lire des données en parallèle. Spanner peut diviser certaines requêtes en fragments plus petits, ou partitions, et extraire les partitions en parallèle. Pour plus d'informations, consultez la section Lire des données en parallèle dans la documentation Spanner. Cette option est limitée aux requêtes dont le premier opérateur du plan d'exécution est un opérateur distributed union. Les autres requêtes renvoient une erreur. Pour afficher le plan d'exécution d'une requête Spanner, consultez la section Comprendre comment Spanner exécute les requêtes.
    • Facultatif : Dans le champ Rôle de base de données, saisissez le nom d'un rôle de base de données Spanner. Si ce champ n'est pas vide, cette connexion interroge Spanner à l'aide de ce rôle de base de données par défaut. Les utilisateurs de Spanner disposant de contrôles d'accès ultraprécis qui envoient des requêtes via cette connexion doivent se voir accorder l'accès à ce rôle par leur administrateur, et le rôle de base de données doit disposer des droits SELECT sur tous les objets de schéma spécifiés dans les requêtes externes. Pour en savoir plus, consultez la page À propos du contrôle d'accès ultraprécis.
    • Facultatif : Pour activer Data Boost, sélectionnez Utiliser Spanner Data Boost. Data Boost vous permet d'exécuter des requêtes d'analyse et des exportations de données avec un impact quasiment nul sur les charges de travail existantes sur l'instance BigQuery provisionnée. Pour activer Data Boost, sélectionnez Data Boost et Lire les données en parallèle.

  4. Cliquez sur Créer une connexion.

bq

Pour créer la connexion, exécutez la commande bq mk avec l'option --connection.

bq mk --connection \
    --connection_type=CLOUD_SPANNER \
    --properties='PROPERTIES' \
    --location=LOCATION \
    --display_name='FRIENDLY_NAME' \
    --description 'DESCRIPTION' \
    CONNECTION_ID

Remplacez les éléments suivants :

  • PROPERTIES : objet JSON comportant les champs suivants :

    • "database" : base de données Spanner pour la connexion.

      À spécifier au format suivant : "projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE".

    • "use_parallelism" : si la valeur est true, cette connexion effectue des lectures parallèles (facultatif).

      La valeur par défaut est false. Spanner peut diviser certaines requêtes en fragments plus petits, ou partitions, et extraire les partitions en parallèle. Pour plus d'informations, consultez la section Lire des données en parallèle dans la documentation Spanner. Cette option est limitée aux requêtes dont le premier opérateur du plan d'exécution est un opérateur distributed union. Les autres requêtes renvoient une erreur. Pour afficher le plan d'exécution d'une requête Spanner, consultez la section Comprendre comment Spanner exécute les requêtes.

    • "database_role" (facultatif) : si elle n'est pas vide, cette connexion interroge Spanner à l'aide de ce rôle de base de données par défaut. Les utilisateurs de Spanner disposant de contrôles d'accès ultraprécis qui envoient des requêtes via cette connexion doivent se voir accorder l'accès à ce rôle par leur administrateur, et le rôle de base de données doit disposer des droits SELECT sur tous les objets de schéma spécifiés dans les requêtes externes.

      Si elle n'est pas spécifiée, la connexion s'authentifie avec des rôles IAM prédéfinis pour Spanner, et le compte principal exécutant des requêtes avec cette connexion doit avoir reçu le rôle IAM roles/spanner.databaseReader.

      Pour en savoir plus, consultez la page À propos du contrôle d'accès ultraprécis.

    • "useDataBoost" : (facultatif) Si la connexion est définie sur true, les utilisateurs peuvent utiliser Data Boost. Data Boost permet aux utilisateurs d'exécuter des requêtes fédérées dans une capacité de calcul distincte, indépendante et distincte des instances provisionnées, afin d'éviter toute incidence sur les charges de travail existantes. Pour activer Data Boost, définissez "useDataBoost" sur true et "use_parallelism" sur true.

      Pour pouvoir utiliser Data Boost, le compte principal qui exécute des requêtes avec cette connexion doit disposer de l'autorisation spanner.databases.useDataBoost. Elle est incluse par défaut dans les rôles roles/spanner.admin et roles/spanner.databaseAdmin.

  • LOCATION : emplacement BigQuery compatible avec votre région de source de données externe.

  • CONNECTION_ID : identifiant de la ressource de connexion.

    L'ID de connexion peut contenir des lettres, des chiffres et des traits de soulignement. Si vous ne fournissez pas d'ID de connexion, BigQuery génère automatiquement un ID unique.

    L'exemple suivant crée une ressource de connexion nommée my_connection_id.

    bq mk --connection \
  --connection_type='CLOUD_SPANNER' \
  --properties='{"database":"projects/my_project/instances/my_instance/databases/database1"}' \
  --project_id=federation-test \
  --location=us \
  my_connection_id

API

Appelez la méthode CreateConnection dans le service ConnectionService.

Partager des connexions avec les utilisateurs

Vous pouvez attribuer les rôles suivants pour permettre aux utilisateurs d'interroger des données et de gérer les connexions :

  • roles/bigquery.connectionUser permet aux utilisateurs de se connecter à des sources de données externes et d'y exécuter des requêtes.

  • roles/bigquery.connectionAdmin permet aux utilisateurs de gérer les connexions.

Pour en savoir plus sur les rôles et les autorisations IAM dans BigQuery, consultez la page Rôles prédéfinis et autorisations.

Sélectionnez l'une des options suivantes :

Console

  1. Accédez à la page BigQuery.

    Accéder à BigQuery

    Les connexions sont répertoriées dans votre projet, dans un groupe appelé Connexions externes.

  2. Dans le volet Explorateur, cliquez sur votre nom de projet > Connexions externes > connexion.

  3. Dans le volet Détails, cliquez sur Partager pour partager une connexion. Ensuite, procédez comme suit :

    1. Dans la boîte de dialogue Autorisations de connexion, partagez la connexion avec d'autres comptes principaux en ajoutant ou en modifiant des comptes principaux.

    2. Cliquez sur Enregistrer.

bq

Vous ne pouvez pas partager de connexion avec l'outil de ligne de commande bq. Pour partager une connexion, utilisez la console Google Cloud ou la méthode de l'API BigQuery Connections permettant le partage de connexion.

API

Utilisez la méthode projects.locations.connections.setIAM dans la section de référence de l'API REST BigQuery Connections et fournissez une instance de la ressource policy.

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes. 

import com.google.api.resourcenames.ResourceName;
import com.google.cloud.bigquery.connection.v1.ConnectionName;
import com.google.cloud.bigqueryconnection.v1.ConnectionServiceClient;
import com.google.iam.v1.Binding;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import java.io.IOException;

// Sample to share connections
public class ShareConnection {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String location = "MY_LOCATION";
    String connectionId = "MY_CONNECTION_ID";
    shareConnection(projectId, location, connectionId);
  }

  static void shareConnection(String projectId, String location, String connectionId)
      throws IOException {
    try (ConnectionServiceClient client = ConnectionServiceClient.create()) {
      ResourceName resource = ConnectionName.of(projectId, location, connectionId);
      Binding binding =
          Binding.newBuilder()
              .addMembers("group:example-analyst-group@google.com")
              .setRole("roles/bigquery.connectionUser")
              .build();
      Policy policy = Policy.newBuilder().addBindings(binding).build();
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(resource.toString())
              .setPolicy(policy)
              .build();
      client.setIamPolicy(request);
      System.out.println("Connection shared successfully");
    }
  }
}

Étapes suivantes