Importer des liens vers des entrées à partir d'une feuille de calcul Google Sheet

Ce document explique comment utiliser l'utilitaire d'importation de liens d'entrée pour importer en masse des liens d'entrée (relations entre les termes du glossaire et les assets de données, y compris les types de liens d'entrée definition, related et synonym) depuis une feuille de calcul Google Sheet vers Knowledge Catalog (anciennement Dataplex Universal Catalog).

Avant de commencer

Avant d'importer des liens d'entrées dans Knowledge Catalog, remplissez les conditions préalables suivantes.

Configurer le compte de service

Pour exécuter l'utilitaire d'importation à l'aide de Google Sheets, 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 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é d'un 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 Gérer l'accès aux comptes de service.

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

    Ouvrez la feuille de calcul Google Sheet que vous souhaitez utiliser pour l'importation, cliquez sur Partager, puis ajoutez l'adresse e-mail du compte de service en tant que 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 liens d'entrée à partir d'une feuille de calcul Google Sheet, demandez à votre administrateur d'accorder 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 liens d'entrée, 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 grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (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
cd dataplex-glossary

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é d'un 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é d'un compte de service :

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

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

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

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Exigences concernant l'importation multiprojets

Pour importer des liens d'entrée dans plusieurs projets Google Cloud , assurez-vous que votre configuration répond aux exigences suivantes avant d'exécuter l'utilitaire d'importation :

  • Configurez les autorisations IAM multi-projets : le compte de service qui exécute le script d'importation doit disposer d'autorisations suffisantes dans tous les projets cibles.

  • Vérifiez l'existence des entrées : les entrées cibles doivent déjà exister dans leurs projets Knowledge Catalog respectifs avant d'exécuter l'importation.

  • Accordez aux agents du service Knowledge Catalog l'accès aux bucket Cloud Storage : les comptes de service Knowledge Catalog de chaque projet cible doivent avoir accès à vos buckets Cloud Storage.

Créer et structurer la Google Sheet à importer

Pour exécuter correctement une importation groupée, vous devez créer une Google Sheet en utilisant un schéma de colonne précis. L'utilitaire d'importation pourra ainsi analyser et valider correctement vos champs de métadonnées. Assurez-vous d'avoir accordé au compte de service Editor l'accès à la Google Sheet.

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

En-tête de colonne Obligatoire ou facultatif Description
entry_link_type Obligatoire La valeur doit être definition, related ou synonym.
source_entry Obligatoire Chemin d'accès complet à l'entrée source au format suivant :
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
target_entry Obligatoire Chemin d'accès complet de l'entrée cible au format suivant :
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
source_path Facultatif Chemin d'accès à la colonne ou au champ pour les liens de définition (par exemple, Schema.column_name).

Configurer des variables d'environnement

Configurez les variables d'environnement suivantes :

# Set your Google Sheet URL
export SPREADSHEET_URL="GOOGLE_SHEET_URL"

# Set your bucket name
export BUCKETS="COMMA_SEPARATED_LIST_OF_BUCKETS"

# Set the project ID
export USER_PROJECT="USER_PROJECT"

Importer des liens vers des entrées à partir de la Google Sheet

Pour importer les liens d'entrée de la Google Sheet dans Knowledge Catalog, exécutez le script entrylinks-import.py :

cd import
python3 entrylinks-import.py \
  --spreadsheet-url="$SPREADSHEET_URL" \
  --buckets="$BUCKETS" \
  --user-project="$USER_PROJECT"

Pour exécuter plusieurs tâches d'importation en parallèle, spécifiez plusieurs buckets Cloud Storage dans le paramètre --buckets. Le script divise les métadonnées en plus petits lots et les traite simultanément dans les buckets, ce qui réduit le temps d'ingestion total.

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.

Étapes suivantes