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 glosarios en Data Catalog, regístrate con este formulario.

Instala gcloud o paquetes de Python.

Roles obligatorios

Para exportar un glosario desde Data Catalog, debes tener el rol roles/datacatalog.glossaryOwner en los proyectos en los que está presente el glosario. Consulta los permisos necesarios para este rol.

Para obtener los permisos que necesitas para importar el glosario empresarial 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 necesarios:

Permisos necesarios

Se requieren los siguientes permisos para importar el glosario empresarial a Knowledge Catalog:

  • dataplex.glossaries.import en el recurso del glosario
  • dataplex.entryGroups.import en el grupo de entradas de Knowledge Catalog que se proporciona en el campo entry_groups y en los grupos de entradas en los que están presentes las entradas de Data Catalog que están vinculadas a los términos del glosario
  • dataplex.entryGroups.useSynonymEntryLink en el grupo de entradas de Knowledge Catalog que se proporciona en el campo entry_groups y en los grupos de entradas en los que están presentes las entradas de Data Catalog que están vinculadas a los términos del glosario
  • dataplex.entryGroups.useRelatedEntryLink en el grupo de entradas de Knowledge Catalog que se proporciona en el campo entry_groups y en los grupos de entradas en los que están presentes las entradas de Data Catalog que están vinculadas a los términos del glosario
  • dataplex.entryLinks.reference en todos los proyectos que se proporcionan en el campo referenced_entry_scopes

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

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

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 \
--user-project="PROJECT_ID" \
--url="DATA_CATALOG_GLOSSARY_URL"

    Reemplaza lo siguiente:

    • PROJECT_ID: el ID del proyecto que contiene el glosario
    • DATA_CATALOG_GLOSSARY_URL: la URL del glosario empresarial de Data Catalog en la Google Cloud consola.

    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
    • Término: 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

    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 y sus categorías y términos se exportan en 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 en 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 en dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import.

  • Los términos de un glosario se pueden vincular 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 de Knowledge Catalog que se exportaron en el paso anterior. En esta sección, se describe cómo importar mediante 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: (opcional) un ID de trabajo de importación de metadatos 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: el URI del bucket o la carpeta de Cloud Storage que contiene el archivo de glosario exportado
    • PROJECT_ID: el número de proyecto que contiene el glosario

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

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

    Si recibes 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 importar mediante la API de trabajos de metadatos.

  1. Crea un bucket de Cloud Storage nuevo y, luego, sube el archivo de vínculos de entrada exportado del paso anterior 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 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: el ID del proyecto que contiene el glosario
    • Opcional: LINKED_GLOSSARY_PROJECT_ID_1: si los términos están vinculados en glosarios de diferentes proyectos, proporciona el ID del proyecto
    • Opcional: LINKED_GLOSSARY_PROJECT_ID_2: si los términos están vinculados en glosarios de diferentes 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 entradas 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 importar mediante 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 al bucket de Cloud Storage. Cada archivo corresponde a un grupo de entradas único que contiene vínculos entre términos y columnas de ese grupo de entradas.

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?