Passer manuellement au glossaire d'entreprise dans Knowledge Catalog

Ce document explique comment migrer de la version preview du glossaire d'entreprise, qui était compatible avec les métadonnées Data Catalog, vers la version disponible de manière générale, qui est compatible avec les métadonnées Knowledge Catalog (anciennement Dataplex Universal Catalog). Le processus de transition consiste à exporter les glossaires, les catégories, les termes et les liens de Data Catalog, puis à les importer dans Knowledge Catalog.

Pour passer manuellement au glossaire d'entreprise dans Knowledge Catalog, procédez comme suit :

Exportez les glossaires et les liens d'entrée de Data Catalog.
Importez les glossaires, les catégories et les termes dans Knowledge Catalog.
Importez les liens entre les termes dans Knowledge Catalog.
Importez les liens entre les termes et les colonnes dans Knowledge Catalog.

Avant de commencer

Pour activer l'exportation à partir des glossaires dans Data Catalog, inscrivez-vous à l'aide de ce formulaire.

Installez les packages gcloud ou Python.

Rôles requis

Pour exporter un glossaire à partir de Data Catalog, vous devez disposer du rôle roles/datacatalog.glossaryOwner sur les projets dans lesquels le glossaire est présent. Consultez les autorisations requises pour ce rôle.

Pour obtenir les autorisations nécessaires pour importer le glossaire d'entreprise dans Knowledge Catalog, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Dataplex (roles/dataplex.admin) sur les projets. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ce rôle prédéfini contient les autorisations requises pour importer le glossaire d'entreprise dans Knowledge Catalog. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour importer le glossaire d'entreprise dans Knowledge Catalog :

dataplex.glossaries.import sur la ressource de glossaire
dataplex.entryGroups.import sur le groupe d'entrées Knowledge Catalog fourni dans le champ entry_groups et sur les groupes d'entrées dans lesquels les entrées Data Catalog sont présentes et liées aux termes du glossaire
dataplex.entryGroups.useSynonymEntryLink sur le groupe d'entrées Knowledge Catalog fourni dans le champ entry_groups et sur les groupes d'entrées dans lesquels les entrées Data Catalog sont présentes et liées aux termes du glossaire
dataplex.entryGroups.useRelatedEntryLink sur le groupe d'entrées Knowledge Catalog fourni dans le champ entry_groups et sur les groupes d'entrées dans lesquels les entrées Data Catalog sont présentes et liées aux termes du glossaire
dataplex.entryLinks.reference sur tous les projets fournis dans le champ referenced_entry_scopes

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

Exporter les glossaires, les catégories et les termes de Data Catalog

Vous ne pouvez exporter qu'un seul glossaire à la fois.

Clonez le dépôt dataplex-labs, puis accédez au sous-répertoire business-glossary-import :

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

Obtenez votre jeton d'accès :

export GCLOUD_ACCESS_TOKEN=$(gcloud auth print-access-token)

Exécutez le script d'exportation :
```
python3 bg_import/business_glossary_export_v2.py \
--user-project="PROJECT_ID" \
--url="DATA_CATALOG_GLOSSARY_URL"
```
Remplacez les éléments suivants :
- PROJECT_ID: ID du projet contenant le glossaire.
- DATA_CATALOG_GLOSSARY_URL : URL du glossaire d'entreprise Data Catalog dans la Google Cloud console.
Le script crée un fichier JSON qui suit le même format que le fichier d'importation de métadonnées utilisé pour les jobs d'importation de métadonnées. Les noms du glossaire, des catégories et des termes utilisent les formats suivants :
- Glossaire : projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/{PROJECT_ID{"</var>"}}/locations/LOCATION_ID/glossaries/GLOSSARY_ID
- Terme : projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM_ID
- Catégorie : projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID
GLOSSARY_ID, CATEGORY_ID, TERM_ID, PROJECT_ID et LOCATION_ID sont identiques aux valeurs du glossaire Data Catalog.

Résultats

La liste suivante décrit les points à noter concernant les résultats :

Les glossaires, leurs catégories et leurs termes sont exportés dans un emplacement mondial, ce qui permet de lier les termes à une entrée dans n'importe quelle région.
Les fichiers exportés se trouvent dans le dossier Exported_Files de dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import. Le nom du fichier est glossary_GLOSSARY_ID.json.
La commande d'exportation crée automatiquement le glossaire dans Knowledge Catalog avec le même GLOSSARY_ID et le même PROJECT_ID dans l'emplacement mondial.
Le script crée un fichier JSON contenant les synonymes et les liens associés entre les termes. Les fichiers exportés se trouvent dans le dossier Exported_Files de dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import. Le nom du fichier est entrylinks_related_synonym_GLOSSARY_ID.json.
Les liens exportés se trouvent dans le dossier Exported_Files de dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import.
Les termes d'un glossaire peuvent être liés à de nombreuses entrées dans de nombreux groupes d'entrées. L'exportation de liens entre les termes et les colonnes crée un fichier pour chaque entryGroup. Le format du nom de fichier est le suivant : entrylinks_definition_export_GLOSSARY_ID_ENTRY_PROJECT_ID_ENTRY_LOCATION_ID_ENTRY_GROUP_ID.json.
L'ID de glossaire dont vous avez besoin pour importer les glossaires, les catégories et les termes s'affiche après l'exécution du script d'exportation.

Importer les glossaires, les catégories et les termes

Vous devez importer les glossaires, les catégories et les termes Knowledge Catalog exportés à l'étape précédente. Cette section explique comment effectuer l'importation à l'aide de l'API de job de métadonnées.

Créez un bucket Cloud Storage, puis importez-y le fichier.
Accordez au compte de service Knowledge Catalog l'accès en lecture au bucket Cloud Storage.

Exécutez un job d'importation de métadonnées pour importer le glossaire.

# Set GCURL alias
alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

# Import CURL Command
gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs\?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -d "$(cat<<EOF
{
"type":"IMPORT",
"import_spec":{
    "log_level": "DEBUG",
    "source_storage_uri": "gs://STORAGE_BUCKET/",
    "entry_sync_mode": "FULL",
    "aspect_sync_mode": "INCREMENTAL",
    "scope": {
      "glossaries": ["projects/PROJECT_ID/locations/global/glossaries/GLOSSARY_ID"]
    }
}
}
EOF
)"

Remplacez les éléments suivants :

JOB_ID: (facultatif) ID de job d'importation de métadonnées, que vous pouvez utiliser pour suivre l'état du job. Si vous ne fournissez pas d'ID, la commande gcurl en génère un unique.
STORAGE_BUCKET: URI du bucket ou du dossier Cloud Storage contenant le fichier de glossaire exporté.
PROJECT_ID: numéro du projet contenant le glossaire.

(Facultatif) Pour suivre l'état du job d'importation de métadonnées, utilisez la metadataJobs.get méthode :
```
gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs/JOB_ID
```
Si des erreurs se produisent dans le job d'importation de métadonnées, elles s'affichent dans les journaux.

Importer les liens entre les termes dans Knowledge Catalog

Vous devez importer les liens entre les termes exportés à l'étape précédente. Cette section explique comment effectuer l'importation à l'aide de l'API de job de métadonnées.

Créez un bucket Cloud Storage, puis importez-y le fichier de liens d'entrée exporté à l'étape précédente.
Accordez au compte de service Knowledge Catalog l'accès en lecture au bucket Cloud Storage.
Exécutez un job d'importation de métadonnées pour importer les liens d'entrée :
```
# Import CURL Command
gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -d "$(cat<<EOF
{
"type": "IMPORT",
"import_spec": {
  "log_level": "DEBUG",
  "source_storage_uri": "gs://STORAGE_BUCKET/",
  "entry_sync_mode": "FULL",
  "aspect_sync_mode": "INCREMENTAL",
  "scope": {
    "entry_groups": ["projects/GLOSSARY_PROJECT_ID/locations/global/entryGroups/@dataplex"],
    "entry_link_types": [
      "projects/dataplex-types/locations/global/entryLinkTypes/synonym",
      "projects/dataplex-types/locations/global/entryLinkTypes/related"
    ],
    "referenced_entry_scopes": ["projects/GLOSSARY_PROJECT_ID","projects/LINKED_GLOSSARY_PROJECT_ID_1","projects/LINKED_GLOSSARY_PROJECT_ID_2"]
  }
}
}
EOF
)"
```
Remplacez les éléments suivants :
- GLOSSARY_PROJECT_ID: ID du projet contenant le glossaire
- (Facultatif) LINKED_GLOSSARY_PROJECT_ID_1 : si les termes sont liés entre des glossaires de différents projets, fournissez l'ID du projet
- (Facultatif) LINKED_GLOSSARY_PROJECT_ID_2 : si les termes sont liés entre des glossaires de différents projets, fournissez l'ID du projet
Veuillez noter les points suivants :
- L'objet entry_groups contient le groupe d'entrées dans lequel les liens d'entrée sont créés. Il s'agit du groupe d'entrées système @dataplex dans le même projet et au même emplacement que le glossaire.
- L'objet entry_link_types vous permet d'importer des synonymes, des termes associés ou les deux :
  - Synonymes : projects/dataplex-types/locations/global/entryLinkTypes/synonym
  - Termes associés : projects/dataplex-types/locations/global/entryLinkTypes/related
- L'objet referenced_entry_scopes inclut les ID de projet des liens d'entrée qui lient les termes de différents glossaires.

Importer les liens entre les termes et les colonnes

Vous devez importer les liens entre les termes et les colonnes exportés à l'étape précédente. Cette section explique comment effectuer l'importation à l'aide de l'API de job de métadonnées.

Importez chaque fichier exporté à l'étape précédente dans un bucket Cloud Storage.
Exécutez une commande d'importation distincte pour chaque fichier importé dans le bucket Cloud Storage. Chaque fichier correspond à un groupe d'entrées unique contenant des liens entre les termes et les colonnes de ce groupe d'entrées.

gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/metadataJobs?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -d "$(cat<<EOF
{
"type": "IMPORT",
"import_spec": {
    "log_level": "DEBUG",
    "source_storage_uri": "gs://STORAGE_BUCKET/",
    "entry_sync_mode": "FULL",
    "aspect_sync_mode": "INCREMENTAL",
    "scope": {
        "entry_groups": ["projects/ENTRY_GROUP_PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/entryGroups/ENTRY_GROUP_ID"],
        "entry_link_types": ["projects/dataplex-types/locations/global/entryLinkTypes/definition"],
        "referenced_entry_scopes": ["projects/ENTRY_GROUP_PROJECT_ID", "projects/GLOSSARY_PROJECT_ID"]
    }
}
}
EOF
)"