Cómo hacer la transición manual al glosario empresarial en Knowledge Catalog

En este documento, se proporcionan instrucciones para migrar de la versión preliminar del glosario empresarial, que admitía metadatos de Data Catalog, a la versión disponible de forma general del glosario empresarial, que admite metadatos de Knowledge Catalog (anteriormente, Dataplex Universal Catalog). El proceso de transición incluye la exportación de glosarios, categorías, términos y vínculos de Data Catalog, y, luego, su importación a Knowledge Catalog.

Para realizar la transición al glosario empresarial en Knowledge Catalog de forma manual, sigue estos pasos:

1. Exporta glosarios y vínculos de entrada desde Data Catalog.
2. Importa glosarios, categorías y términos a Knowledge Catalog.
3. Importa vínculos entre términos a Knowledge Catalog.
4. Importa vínculos entre términos y columnas a Knowledge Catalog.

Antes de comenzar

Para habilitar la exportación desde los glosarios en Data Catalog, regístrate con el formulario de registro.

Instala gcloud o paquetes de Python.

Roles obligatorios

Para exportar un glosario de Data Catalog, debes tener el rol roles/datacatalog.glossaryOwner en los proyectos en los que se encuentra el glosario. Consulta los permisos necesarios para este rol.

Para obtener los permisos que necesitas para importar el glosario de la empresa a Knowledge Catalog, pídele a tu administrador que te otorgue el rol de IAM de Administrador de Dataplex (roles/dataplex.admin) en los proyectos. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para importar el glosario empresarial a Knowledge Catalog. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Exporta glosarios, categorías y términos de Data Catalog

Solo puedes exportar un glosario a la vez.

1. Clona el repositorio dataplex-labs y, luego, cambia los directorios al subdirectorio 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
   

2. Obtén tu token de acceso:

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

3. Ejecuta la secuencia de comandos de exportación:

   python3 bg_import/business_glossary_export_v2.py \
   --project="PROJECT_ID" \
   --url="DATA_CATALOG_GLOSSARY_URL"

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID del proyecto que contiene el glosario. Este proyecto también se usa para la facturación y la cuota.
   • DATA_CATALOG_GLOSSARY_URL: Es la URL completa del glosario empresarial del Data Catalog tal como aparece en la consola deGoogle Cloud .

   Ejemplo: https://console.cloud.google.com/datacatalog/glossaries/projects/my-project/locations/us-central1/entryGroups/my-entry-group/glossaries/my-glossary

   La secuencia de comandos crea un archivo JSON que sigue el mismo formato que el archivo de importación de metadatos que se usa para los trabajos de importación de metadatos. Los nombres del glosario, las categorías y los términos usan los siguientes formatos:

   • Glosario: projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/{PROJECT_ID{"</var>"}}/locations/LOCATION_ID/glossaries/GLOSSARY_ID
   • Período: projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM_ID
   • Categoría: projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID

   Los campos GLOSSARY_ID, CATEGORY_ID, TERM_ID, PROJECT_ID y LOCATION_ID son los mismos que los valores del glosario de Data Catalog.

Resultados

En la siguiente lista, se describen los aspectos que debes tener en cuenta sobre los resultados:

• Los glosarios, sus categorías y sus términos se exportan a una ubicación global, lo que permite que los términos se vinculen a una entrada en cualquier región.

• Los archivos exportados se encuentran en la carpeta Exported_Files de dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import. El nombre del archivo es glossary_GLOSSARY_ID.json.

• El comando de exportación crea automáticamente el glosario en Knowledge Catalog con el mismo GLOSSARY_ID y PROJECT_ID en la ubicación global.

• La secuencia de comandos crea un archivo JSON que contiene los sinónimos y los vínculos relacionados entre los términos. Los archivos exportados se encuentran en la carpeta Exported_Files en dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import. El nombre del archivo es entrylinks_related_synonym_GLOSSARY_ID.json.

• Los vínculos exportados se encuentran en la carpeta Exported_Files de dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import.

• Los términos de un glosario pueden vincularse a muchas entradas en muchos grupos de entradas. La exportación de vínculos entre términos y columnas crea un archivo para cada entryGroup. El formato del nombre de archivo es entrylinks_definition_export_GLOSSARY_ID_ENTRY_PROJECT_ID_ENTRY_LOCATION_ID_ENTRY_GROUP_ID.json.

• El ID del glosario que necesitas para importar glosarios, categorías y términos aparece después de que se ejecuta la secuencia de comandos de exportación.

Importa glosarios, categorías y términos

Debes importar los glosarios, las categorías y los términos del Catálogo de conocimiento que se exportaron en el paso anterior. En esta sección, se describe cómo realizar la importación con la API de trabajos de metadatos.

1. Crea un bucket de Cloud Storage y, luego, sube el archivo al bucket.

2. Otorga acceso de lectura a la cuenta de servicio de Knowledge Catalog al bucket de Cloud Storage.

3. Ejecuta un trabajo de importación de metadatos para importar el glosario.

   # 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
   )"

   Reemplaza lo siguiente:

   • JOB_ID: Es el ID de un trabajo de importación de metadatos (opcional) que puedes usar para hacer un seguimiento del estado del trabajo. Si no proporcionas un ID, el comando gcurl genera un ID único.
   • STORAGE_BUCKET: Es el URI del bucket o la carpeta de Cloud Storage que contiene el archivo de glosario exportado.
   • PROJECT_ID: Es el número del proyecto que contiene el glosario.

4. Opcional: Para hacer un seguimiento del estado del trabajo de importación de metadatos, usa el método metadataJobs.get:

   gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs/JOB_ID

   Si se produce algún error en el trabajo de importación de metadatos, aparecerá en los registros.

Importa vínculos entre términos a Knowledge Catalog

Debes importar los vínculos entre los términos que se exportaron en el paso anterior. En esta sección, se describe cómo realizar la importación con la API de trabajos de metadatos.

1. Crea un nuevo bucket de Cloud Storage y, luego, sube a él el archivo de vínculos de entrada que exportaste en el paso anterior.

2. Otorga acceso de lectura a la cuenta de servicio de Knowledge Catalog al bucket de Cloud Storage.

3. Ejecuta un trabajo de importación de metadatos para importar los vínculos de entrada:

   # 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
   )"

   Reemplaza lo siguiente:

   • GLOSSARY_PROJECT_ID: ID del proyecto que contiene el glosario
   • Opcional: LINKED_GLOSSARY_PROJECT_ID_1: Si los términos están vinculados en diferentes glosarios de distintos proyectos, proporciona el ID del proyecto.
   • Opcional: LINKED_GLOSSARY_PROJECT_ID_2: Si los términos están vinculados en diferentes glosarios de distintos proyectos, proporciona el ID del proyecto.

   Ten en cuenta lo siguiente:

   • El objeto entry_groups contiene el grupo de entradas en el que se crean los vínculos de entrada. Este es el grupo de entrada del sistema @dataplex en el mismo proyecto y ubicación que el glosario.

   • El objeto entry_link_types te permite importar sinónimos, términos relacionados o ambos:

     • Sinónimos: projects/dataplex-types/locations/global/entryLinkTypes/synonym
     • Términos relacionados: projects/dataplex-types/locations/global/entryLinkTypes/related

   • El objeto referenced_entry_scopes incluye los IDs de proyecto de los vínculos de entrada que vinculan términos de diferentes glosarios.

Importa vínculos entre términos y columnas

Debes importar los vínculos entre los términos y las columnas que se exportaron en el paso anterior. En esta sección, se describe cómo realizar la importación con la API de trabajos de metadatos.

1. Sube cada archivo exportado en el paso anterior a un bucket de Cloud Storage.

2. Ejecuta un comando de importación independiente para cada archivo subido en el bucket de Cloud Storage. Cada archivo corresponde a un grupo de entrada único que contiene vínculos entre los términos y las columnas de ese grupo de entrada.

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
)"

¿Qué sigue?

• Administra un glosario empresarial en Knowledge Catalog
• Transición a Knowledge Catalog