Transición al glosario empresarial en Knowledge Catalog

En este documento, se proporcionan instrucciones para migrar en un solo paso desde 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 en Knowledge Catalog (anteriormente Dataplex Universal Catalog). La migración a la versión disponible de forma general te permite usar las capacidades mejoradas y una integración más profunda con los metadatos de Knowledge Catalog, lo que ofrece una mayor estabilidad, funciones nuevas y asistencia de producción completa. Este proceso actualiza automáticamente tus glosarios para admitir metadatos de Knowledge Catalog.

Nota: Si ya iniciaste el proceso de migración con el proceso manual para migrar tus glosarios y deseas acceder a esas instrucciones, consulta Cómo realizar la transición manual al glosario empresarial en Knowledge Catalog.

Antes de comenzar

1. Instala gcloud o paquetes de Python. Autentica tu cuenta de usuario y las credenciales predeterminadas de la aplicación (ADC) que usan las bibliotecas de Python. Ejecuta los siguientes comandos y sigue las instrucciones basadas en el navegador:

   gcloud init
   gcloud auth login
   gcloud auth application-default login
   

2. Habilita las siguientes APIs:

   • API de Dataplex
   • API de Data Catalog
   • API de Cloud Resource Manager
   • API de Cloud Storage

3. Crea uno o varios buckets de Cloud Storage en cualquiera de tus proyectos. Los buckets se usarán como una ubicación temporal para los archivos de importación. Cuantos más buckets proporciones, más rápida será la importación. Otorga el rol de IAM de administrador de almacenamiento a la cuenta de servicio que ejecuta la migración:

   [e-mail]

   Reemplaza MIGRATION_PROJECT_ID por el proyecto desde el que migras los glosarios.

4. Configura el repositorio:

   1. Clona el repositorio:

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

   2. Instala los paquetes necesarios:

      pip3 install -r requirements.txt
      cd migration
      

      Nota: Si tienes problemas para instalar el paquete, sigue los pasos para crear un nuevo entorno virtual de Python.

Roles obligatorios

Para obtener los permisos que necesitas para migrar glosarios de Data Catalog a Knowledge Catalog, pídele a tu administrador que te otorgue los siguientes roles de IAM:

• Propietario del glosario de Data Catalog (roles/datacatalog.glossaryOwner) en tu proyecto
• Administrador de Dataplex (roles/dataplex.admin) en tu proyecto

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para migrar glosarios de Data Catalog a Knowledge Catalog. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Los siguientes permisos son necesarios para migrar glosarios de Data Catalog a Knowledge Catalog:

• datacatalog.glossaries.get en el proyecto desde el que migras los glosarios
• datacatalog.glossaries.list en el proyecto desde el que migras los glosarios
• dataplex.glossaries.create en el proyecto en el que se crean glosarios en Knowledge Catalog
• dataplex.glossaries.update en el proyecto en el que se actualizarán los glosarios en Knowledge Catalog

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

Para obtener más información sobre Identity and Access Management (IAM) de Knowledge Catalog, consulta Administra el acceso con IAM.

Ejecuta la secuencia de comandos de migración

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2

Reemplaza lo siguiente:

• USER_PROJECT_ID: El ID del proyecto que se migrará.

  MIGRATION_PROJECT_ID hace referencia al proyecto de origen que contiene los glosarios de Data Catalog que deseas exportar. USER_PROJECT_ID es el proyecto que se usa para la facturación y la atribución de cuotas para las llamadas a la API que genera la secuencia de comandos.

• BUCKET1 y BUCKET2: Los IDs de bucket de Cloud Storage que se usarán para la importación.

  Puedes proporcionar uno o más buckets. Para los argumentos del bucket, proporciona una lista separada por comas de nombres de buckets sin espacios (por ejemplo, --buckets=bucket-one,bucket-two). No se requiere una asignación uno a uno entre buckets y glosarios; la secuencia de comandos ejecuta los trabajos de importación en paralelo, lo que acelera la migración.

Si los problemas de permisos impiden que la secuencia de comandos descubra automáticamente los IDs de tu organización, usa la marca --orgIds para especificar las organizaciones que la secuencia de comandos puede usar para buscar activos de datos vinculados a términos del glosario.

Nota: No edites los archivos JSON exportados. La secuencia de comandos genera archivos en el formato que requiere la API de importación de Dataplex. Si modificas el formato, es posible que fallen los trabajos de importación.

Glosarios de alcance en la migración

Para migrar solo glosarios específicos, define su alcance proporcionando sus URLs respectivas.

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2 --glossaries="GLOSSARY_URL1","GLOSSARY_URL2"

Reemplaza GLOSSARY_URL1 (y GLOSSARY_URL2) por las URLs de los glosarios que migras. Puedes proporcionar una o más URLs de glosario.

Cuando se ejecuta la migración, la cantidad de trabajos de importación puede ser menor que la cantidad de glosarios exportados. Esto sucede cuando se crean directamente glosarios vacíos que no requieren un trabajo de importación en segundo plano.

Reanuda la migración para las fallas del trabajo de importación

La presencia de archivos después de la migración indica que fallaron algunos trabajos de importación. Para reanudar la migración, ejecuta el siguiente comando:

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2 --resume-import

Si encuentras fallas, vuelve a ejecutar el comando resume. La secuencia de comandos procesa solo los archivos que no se importaron y borraron correctamente.

La secuencia de comandos aplica verificaciones de dependencia para los vínculos de entrada y los vínculos entre glosarios. Un archivo de vínculo de entrada se importa solo si su glosario superior se importó correctamente. Del mismo modo, un vínculo entre términos se importa solo si todos los términos a los que se hace referencia se importaron correctamente.

Nota: Es posible que se agreguen IDs aleatorios a los nombres de glosarios, vínculos de entrada y trabajos en los registros o archivos generados. Estos IDs son para la exclusividad interna del backend y no afectan los nombres ni la estructura de los glosarios migrados finales.

Solucionar problemas

En esta sección, se proporcionan soluciones para errores comunes.

• Permiso denegado / Error 403: Asegúrate de que el usuario o la cuenta de servicio tengan el rol de editor de Dataplex en el proyecto de destino y el rol de visualizador de Dataplex en el proyecto de origen.

• ModuleNotFoundError: Asegúrate de haber activado tu entorno virtual de Python y de haber instalado los paquetes necesarios con pip3 install -r requirements.txt.

• TimeoutError / ssl.SSLError: Estos errores a nivel de la red pueden deberse a firewalls, proxies o conexiones lentas. La secuencia de comandos tiene un tiempo de espera de 5 minutos. Los problemas persistentes pueden requerir que verifiques la configuración de tu red local.

• No se encontró el método (no se pueden recuperar entradas): Este error suele indicar que tu proyecto de usuario no está autorizado para llamar a la API, lo que impide la recuperación de las entradas necesarias.