Cette page a été traduite par l'API Cloud Translation.

Créer des ensembles de données externes Spanner

Ce document explique comment créer un ensemble de données externe (également appelé ensemble de données fédéré) dans BigQuery associé à une base de données existante dans Spanner.

Un ensemble de données externe est une connexion entre BigQuery et une source de données externe au niveau de l'ensemble de données. Il vous permet d'interroger les données transactionnelles dans les bases de données Spanner avec GoogleSQL sans déplacer les données de Spanner vers le stockage BigQuery.

Les tables d'un ensemble de données externe sont renseignées automatiquement à partir des tables de la source de données externe correspondante. Vous pouvez interroger ces tables directement dans BigQuery, mais vous ne pouvez pas les modifier, les ajouter ni les supprimer. Cependant, toutes les mises à jour que vous effectuez dans la source de données externe sont automatiquement répercutées dans BigQuery.

Autorisations requises

Pour obtenir l'autorisation dont vous avez besoin pour créer un ensemble de données externe, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur BigQuery (roles/bigquery.user). Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient l'autorisation bigquery.datasets.create, qui est requise pour créer un ensemble de données externe.

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

Pour plus d'informations sur les rôles et les autorisations IAM dans BigQuery, consultez la page Présentation d'IAM.

Créer un ensemble de données externe

Pour créer un ensemble de données externe, procédez comme suit:

Console

Ouvrez la page BigQuery dans la console Google Cloud.

Accéder à BigQuery
Dans le panneau Explorer, sélectionnez le projet dans lequel vous souhaitez créer l'ensemble de données.
Développez l'option Actions, puis cliquez sur Créer un ensemble de données.
Sur la page Créer un ensemble de données, procédez comme suit :
- Pour Dataset ID (ID de l'ensemble de données), renseignez un ensemble de données unique.
- Dans Type d'emplacement, choisissez un emplacement pour l'ensemble de données, par exemple us-central1 ou us multirégional. Une fois l'ensemble de données créé, l'emplacement ne peut plus être modifié.
- Pour Ensemble de données externe, procédez comme suit :
  - Cochez la case Associer à un ensemble de données externe.
  - Dans le champ Type d'ensemble de données externe, sélectionnez Spanner.
  - Dans le champ Source externe, saisissez l'identifiant complet de votre base de données Spanner au format suivant: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Par exemple : projects/my_project/instances/my_instance/databases/my_database.
  - Vous pouvez éventuellement saisir le nom d'un rôle de base de données Spanner dans Rôle de base de données. Pour en savoir plus, consultez les rôles de base de données utilisés pour créer des connexions Spanner.
- Ne modifiez pas les autres paramètres.
Cliquez sur Créer l'ensemble de données.

SQL

Utilisez l'instruction LDD (langage de définition de données) CREATE EXTERNAL SCHEMA.

Dans la console Google Cloud, accédez à la page BigQuery.

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
CREATE EXTERNAL SCHEMA DATASET_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
```
Remplacez les éléments suivants :
- DATASET_NAME : nom de votre nouvel ensemble de données dans BigQuery.
- SPANNER_EXTERNAL_SOURCE: nom complet de la base de données Spanner, avec un préfixe identifiant la source, au format suivant: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Exemples : google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database ou google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
- LOCATION: emplacement de votre nouvel ensemble de données dans BigQuery, par exemple, us-central1. Une fois que vous avez créé un ensemble de données, vous ne pouvez plus modifier son emplacement.
Cliquez sur Exécuter.

Pour en savoir plus sur l'exécution des requêtes, consultez Exécuter une requête interactive.

bq

Dans un environnement de ligne de commande, créez un ensemble de données externe à l'aide de la commande bq mk:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

Remplacez les éléments suivants :

LOCATION : emplacement de votre nouvel ensemble de données dans BigQuery, par exemple, us-central1. Une fois que vous avez créé un ensemble de données, vous ne pouvez plus modifier son emplacement. Vous pouvez définir une valeur d'emplacement par défaut à l'aide du fichier .bigqueryrc.
SPANNER_EXTERNAL_SOURCE: nom complet de la base de données Spanner, avec un préfixe identifiant la source, au format suivant: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Par exemple, google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database ou google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
DATASET_NAME : nom de votre nouvel ensemble de données dans BigQuery. Pour créer un ensemble de données dans un projet autre que votre projet par défaut, ajoutez l'ID du projet au nom de l'ensemble de données de la manière suivante : PROJECT_ID:DATASET_NAME.

Terraform

Utilisez la ressource google_bigquery_dataset.

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.

L'exemple suivant crée un ensemble de données externe Spanner:

resource "google_bigquery_dataset" "default" {
  dataset_id    = "my_external_dataset"
  friendly_name = "My external dataset"
  description   = "This is a test description."
  location      = "US"
  external_dataset_reference {
    # The full identifier of your Spanner database.
    external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
    # Must be empty for a Spanner external dataset.
    connection = ""
  }
}

Pour appliquer votre configuration Terraform dans un projet Google Cloud, suivez les procédures des sections suivantes.

Préparer Cloud Shell

Lancez Cloud Shell.
Définissez le projet Google Cloud par défaut dans lequel vous souhaitez appliquer vos configurations Terraform.

Vous n'avez besoin d'exécuter cette commande qu'une seule fois par projet et vous pouvez l'exécuter dans n'importe quel répertoire.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Les variables d'environnement sont remplacées si vous définissez des valeurs explicites dans le fichier de configuration Terraform.

Préparer le répertoire

Chaque fichier de configuration Terraform doit avoir son propre répertoire (également appelé module racine).

Dans Cloud Shell, créez un répertoire et un nouveau fichier dans ce répertoire. Le nom du fichier doit comporter l'extension .tf, par exemple main.tf. Dans ce tutoriel, le fichier est appelé main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si vous suivez un tutoriel, vous pouvez copier l'exemple de code dans chaque section ou étape.

Copiez l'exemple de code dans le fichier main.tf que vous venez de créer.

Vous pouvez également copier le code depuis GitHub. Cela est recommandé lorsque l'extrait Terraform fait partie d'une solution de bout en bout.
Examinez et modifiez les exemples de paramètres à appliquer à votre environnement.
Enregistrez les modifications.
Initialisez Terraform. Cette opération n'est à effectuer qu'une seule fois par répertoire.
```
terraform init
```
Vous pouvez également utiliser la dernière version du fournisseur Google en incluant l'option -upgrade :
```
terraform init -upgrade
```

Appliquer les modifications

Examinez la configuration et vérifiez que les ressources que Terraform va créer ou mettre à jour correspondent à vos attentes :
```
terraform plan
```
Corrigez les modifications de la configuration si nécessaire.
Appliquez la configuration Terraform en exécutant la commande suivante et en saisissant yes lorsque vous y êtes invité :
```
terraform apply
```
Attendez que Terraform affiche le message "Apply completed!" (Application terminée).
Ouvrez votre projet Google Cloud pour afficher les résultats. Dans la console Google Cloud, accédez à vos ressources dans l'interface utilisateur pour vous assurer que Terraform les a créées ou mises à jour.

API

Appelez la méthode datasets.insert avec une ressource d'ensemble de données et un champ externalDatasetReference définis pour votre base de données Spanner.

Notez que les noms des tables des ensembles de données externes ne sont pas sensibles à la casse.

Répertorier les tables dans un ensemble de données externe

Pour répertorier les tables disponibles pour l'interrogation dans votre ensemble de données externe, consultez la section Répertorier les ensembles de données.

Obtenir des informations sur la table

Pour obtenir des informations sur les tables de votre ensemble de données externe, telles que les détails du schéma, consultez la section Obtenir des informations sur la table.

Contrôler l'accès aux tables

Les ensembles de données externes Spanner sont compatibles avec les identifiants des utilisateurs finaux. Cela signifie que l'accès aux tables Spanner à partir d'ensembles de données externes est contrôlé par Spanner. Les utilisateurs ne peuvent interroger ces tables que s'ils ont un accès accordé dans Spanner.

Interroger des données Spanner

L'interrogation de tables dans des ensembles de données externes est la même que l'interrogation de tables dans n'importe quel autre ensemble de données BigQuery. Toutefois, les opérations de modification de données (LMD) ne sont pas acceptées.

Les requêtes adressées aux tables des ensembles de données externes Spanner utilisent Data Boost par défaut, et vous ne pouvez pas modifier ce paramètre. Vous avez donc besoin d'autorisations supplémentaires pour exécuter ces requêtes.

Créer une vue dans un ensemble de données externe

Vous ne pouvez pas créer de vue dans un ensemble de données externe. Toutefois, vous pouvez créer une vue dans un ensemble de données standard basée sur une table d'un ensemble de données externe. Pour en savoir plus, consultez la section Créer des vues.

Supprimer un ensemble de données externe

La suppression d'un ensemble de données externe est identique à la suppression de tout autre ensemble de données BigQuery. La suppression d'ensembles de données externes n'a aucune incidence sur les tables de la base de données Spanner. Pour en savoir plus, consultez la section Supprimer des ensembles de données.

Limites

Les limitations des requêtes fédérées BigQuery s'appliquent.
Seules les tables d'un schéma Spanner par défaut sont accessibles dans BigQuery. Les tables des schémas de noms ne sont pas acceptées.
Si une table de la base de données Spanner contient une colonne d'un type non compatible avec BigQuery, cette colonne ne sera pas accessible côté BigQuery.
Vous ne pouvez pas ajouter, supprimer ni mettre à jour des données ni des métadonnées dans les tables d'un ensemble de données externe Spanner.
Vous ne pouvez pas créer de tables, de vues ni de vues matérialisées dans un ensemble de données externe Spanner.
Les vues INFORMATION_SCHEMA ne sont pas prises en charge.
La mise en cache des métadonnées n'est pas prise en charge.
Les paramètres au niveau de l'ensemble de données liés aux valeurs par défaut de création de table n'affectent pas les ensembles de données externes, car vous ne pouvez pas créer de tables manuellement.
Les bases de données Spanner qui utilisent le dialecte PostgreSQL ne sont pas compatibles.
Les API Write et Read ne sont pas compatibles.
La sécurité au niveau des lignes, la sécurité au niveau des colonnes et le masquage des données ne sont pas acceptés.
Les vues matérialisées basées sur des tables d'ensembles de données externes Spanner ne sont pas acceptées.
L'intégration à Dataplex n'est pas disponible. Par exemple, les profils de données et les analyses de la qualité des données ne sont pas acceptés.
Les tags au niveau de la table ne sont pas acceptés.
La saisie semi-automatique SQL ne fonctionne pas avec les tables externes Spanner lorsque vous écrivez des requêtes.
L'option Analyser avec la protection des données sensibles n'est pas disponible pour les ensembles de données externes.
Vous pouvez créer une vue autorisée qui référence l'ensemble de données externe Spanner. Toutefois, lorsque cette vue est interrogée, l'EUC d'une personne qui exécute une requête est envoyée à Spanner.

Étape suivante

En savoir plus sur les requêtes fédérées Spanner