Importer des glossaires d'entreprise à partir d'une feuille de calcul Google Sheet

Ce document explique comment utiliser l'utilitaire d'importation de glossaires pour importer en bloc des glossaires, des catégories et des termes à partir d'une feuille de calcul Google Sheet dans Knowledge Catalog (anciennement Dataplex Universal Catalog).

L'utilitaire glossary_import analyse et valide les données d'une Google Sheet, les convertit dans un format compatible avec l'API CreateMetadataJob de Knowledge Catalog, puis les importe dans un bucket Cloud Storage avant de déclencher la tâche d'importation.

Avant de commencer

Avant d'importer des glossaires, remplissez les conditions préalables suivantes.

Configurer le compte de service

Pour exécuter l'utilitaire d'importation à l'aide d'une Google Sheet, vous devez configurer un compte de service disposant des autorisations nécessaires pour accéder à l'API Google Sheets et emprunter l'identité de vos identifiants utilisateur :

  1. Identifiez ou créez un compte de service.

    Sélectionnez un compte de service existant ou créez-en un dans le projet dans lequel vous exécutez l'utilitaire d'importation. Pour en savoir plus, consultez la section Créer des comptes de service. Notez l'adresse e-mail du compte de service (par exemple, SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com).

  2. Configurez l'emprunt d'identité du compte de service.

    Pour exécuter le script de l'utilitaire d'importation en local, votre compte utilisateur doit être autorisé à emprunter l'identité du compte de service. Attribuez à votre compte utilisateur le rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) sur le compte de service.

    Pour en savoir plus, consultez la page Gérer l'accès aux comptes de service.

  3. Accordez au compte de service l'accès Editor à la Google Sheet.

    Ouvrez la Google Sheet que vous souhaitez utiliser pour le processus d'importation, cliquez sur Partager, puis ajoutez l'adresse e-mail du compte de service en tant qu'Editor. Cette autorisation permet au compte de service de lire ou d'écrire des données dans votre feuille.

Créer un bucket Cloud Storage

Créez un bucket Cloud Storage qui servira de zone de préparation pour les fichiers d'importation.

Rôles requis

Pour vous assurer que le compte de service dispose des autorisations nécessaires pour importer des glossaires à partir d'une Google Sheet, demandez à votre administrateur d'attribuer les rôles IAM suivants au compte de service :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Votre administrateur peut également attribuer au compte de service les autorisations requises à l'aide de rôles personnalisés ou d'autres rôles prédéfinis.

Activer les API

Pour importer des glossaires, activez les API suivantes dans votre projet :

Rôles requis pour activer les API

Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez l'obtenir via le rôle Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer les API

Configurer le dépôt Git

Clonez le dépôt dataplex-labs :

git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
cd dataplex-labs/dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import/dataplex-glossary/import

Installer des dépendances

Installez les dépendances Python requises :

pip3 install -r requirements.txt

Si vous rencontrez des problèmes lors de l'installation du package, configurez un nouvel environnement de développement Python.

S'authentifier et configurer l'emprunt d'identité du compte de service

Initialisez la Google Cloud CLI et authentifiez-vous à l'aide des identifiants par défaut de l'application (ADC) avec l'emprunt d'identité du compte de service :

# Set your service account email address
SA_EMAIL="SERVICE_ACCOUNT_EMAIL"

# Authenticate ADC using service account impersonation and required scopes
gcloud auth application-default login \
  --impersonate-service-account="${SA_EMAIL}" \
  --scopes="https://www.googleapis.com/auth/spreadsheets"

Remplacez SERVICE_ACCOUNT_EMAIL par l'ID de l'adresse e-mail du compte de service. Exemple :

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Créer et structurer la Google Sheet pour l'importation

Pour exécuter correctement une importation en bloc, vous devez créer une feuille de calcul Google Sheet à l'aide d'un schéma de colonne précis afin que l'utilitaire d'importation puisse analyser et valider correctement vos champs de métadonnées. Assurez-vous d'avoir accordé au compte de service l'accès Editor à la Google Sheet.

La première ligne de la feuille doit contenir les en-têtes de schéma exacts suivants, qui sont sensibles à la casse :

Champ Obligatoire ou facultatif Description
id Obligatoire Identifiant unique du terme ou de la catégorie dans le glossaire.
parent Facultatif ID de la catégorie parente. Si ce champ est vide, l'élément est un enfant de niveau racine du glossaire. Notez que l'ID parent référencé doit exister dans la feuille et appartenir à une catégorie.
display_name Obligatoire Nom à afficher du terme ou de la catégorie.
description Facultatif Brève description du terme ou de la catégorie.
overview Facultatif Description au format texte enrichi du terme ou de la catégorie (compatible avec les balises HTML).
type Obligatoire Type de ligne. Les valeurs valides sont TERM ou CATEGORY.
contact1_email Facultatif Adresse e-mail de l'intendant de données principal pour le terme ou la catégorie.
contact1_name Facultatif Nom de l'intendant de données principal pour le terme ou la catégorie.
contact2_email Facultatif Adresse e-mail de l'intendant de données secondaire pour le terme ou la catégorie.
contact2_name Facultatif Nom de l'intendant de données secondaire pour le terme ou la catégorie.
label1_key Facultatif Clé du premier libellé attribué.
label1_value Facultatif Valeur du premier libellé attribué.
label2_key Facultatif Clé du deuxième libellé attribué.
label2_value Facultatif Valeur du deuxième libellé attribué.

Importer un glossaire à partir de la Google Sheet

Après avoir configuré votre environnement et préparé votre Google Sheet, exécutez le script glossary_import.py :

python3 bg_import/dataplex-glossary/glossary_import.py

L'utilitaire d'importation affiche le résultat de l'exécution de l'API CreateMetadataJob directement dans votre terminal. Vérifiez que l'état de la tâche indique qu'elle a réussi.

Vous pouvez consulter les journaux d'exécution dans le répertoire logs/ de votre chemin d'exécution local. Ces journaux vous aident à auditer le processus de transfert et à identifier les entrées ignorées ou les avertissements de mise en forme.

Étape suivante