Importa glosarios empresariales desde una hoja de cálculo de Google

En este documento, se explica cómo usar la utilidad de importación de glosarios para importar de forma masiva glosarios, categorías y términos desde una hoja de cálculo de Google a Knowledge Catalog (anteriormente, Dataplex Universal Catalog).

La utilidad glossary_import analiza y valida los datos de una hoja de cálculo de Google, los convierte a un formato compatible con la API de CreateMetadataJob de Knowledge Catalog y los sube a un bucket de Cloud Storage antes de activar el trabajo de importación.

Antes de comenzar

Antes de importar glosarios, completa los siguientes requisitos previos.

Configura la cuenta de servicio

Para ejecutar la utilidad de importación con una hoja de cálculo de Google, debes configurar una cuenta de servicio con los permisos necesarios para acceder a la API de Hojas de cálculo de Google y suplantar tus credenciales de usuario:

  1. Identifica o crea una cuenta de servicio.

    Selecciona una cuenta de servicio existente o crea una nueva en el proyecto en el que ejecutas la utilidad de importación. Para obtener más información, consulta Crea cuentas de servicio. Toma nota del correo electrónico de la cuenta de servicio (por ejemplo, SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com).

  2. Configura el robo de identidad de la cuenta de servicio.

    Para ejecutar el script de la utilidad de importación de forma local, tu cuenta de usuario debe tener permiso para suplantar la identidad de la cuenta de servicio. Otorga a tu cuenta de usuario el rol de creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) en la cuenta de servicio.

    Para obtener más información, consulta Administra el acceso a las cuentas de servicio.

  3. Otorga a la cuenta de servicio Editor acceso a la Hoja de cálculo de Google.

    Abre la Hoja de cálculo de Google que quieras usar para el proceso de importación, haz clic en Compartir y agrega el correo electrónico de la cuenta de servicio como Editor. Este permiso permite que la cuenta de servicio lea o escriba datos en tu hoja.

Cree un bucket de Cloud Storage

Crea un bucket de Cloud Storage para que funcione como área de etapa de pruebas para los archivos de importación.

Roles obligatorios

Para garantizar que la cuenta de servicio tenga los permisos necesarios para importar glosarios desde una hoja de cálculo de Google, pídele a tu administrador que le otorgue los siguientes roles de IAM a la cuenta de servicio:

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

Es posible que tu administrador también pueda otorgar a la cuenta de servicio los permisos necesarios a través de roles personalizados o de otros roles predefinidos.

Habilita las APIs

Para importar glosarios, habilita las siguientes APIs en tu proyecto:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

Habilitar las API

Configura el repositorio de Git

Clona el repositorio 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

Instala dependencias

Instala las dependencias de Python necesarias:

pip3 install -r requirements.txt

Si tienes algún problema con la instalación del paquete, configura un nuevo entorno de desarrollo de Python.

Autentica y configura la suplantación de identidad de la cuenta de servicio

Inicializa Google Cloud CLI y autentícate con las credenciales predeterminadas de la aplicación (ADC) con la identidad temporal de la cuenta de servicio:

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

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

Reemplaza SERVICE_ACCOUNT_EMAIL por el ID de correo electrónico de la cuenta de servicio. Por ejemplo:

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Crea y estructura la hoja de cálculo de Google para la importación

Para ejecutar correctamente una importación masiva, debes crear una nueva hoja de cálculo de Google con un esquema de columnas preciso para que la utilidad de importación pueda analizar y validar correctamente tus campos de metadatos. Asegúrate de haber otorgado a la cuenta de servicio acceso Editor a la Hoja de cálculo de Google.

La primera fila de la hoja debe contener estos encabezados de esquema exactos y que distinguen mayúsculas de minúsculas:

Campo Obligatorio u opcional Descripción
id Obligatorio Es un identificador único para el término o la categoría dentro del glosario.
parent Opcional Es el ID de la categoría principal. Si está vacío, el elemento es un elemento secundario de nivel raíz del glosario. Ten en cuenta que el ID principal al que se hace referencia debe existir en la hoja y pertenecer a una categoría.
display_name Obligatorio Es el nombre visible del término o la categoría.
description Opcional Es una breve descripción del término o la categoría.
overview Opcional Es una descripción en texto enriquecido del término o la categoría (admite etiquetas HTML).
type Obligatorio Es el tipo de fila. Los valores válidos son TERM o CATEGORY.
contact1_email Opcional Dirección de correo electrónico del administrador de datos principal del término o la categoría.
contact1_name Opcional Nombre del administrador de datos principal del término o la categoría.
contact2_email Opcional Dirección de correo electrónico del administrador de datos secundario para el término o la categoría.
contact2_name Opcional Nombre del administrador de datos secundario del término o la categoría.
label1_key Opcional Es la clave de la primera etiqueta asignada.
label1_value Opcional Es el valor de la primera etiqueta asignada.
label2_key Opcional Es la clave de la segunda etiqueta asignada.
label2_value Opcional Valor de la segunda etiqueta asignada.

Importa el glosario de la hoja de cálculo de Google

Después de configurar tu entorno y preparar tu Hoja de cálculo de Google, ejecuta la secuencia de comandos glossary_import.py:

python3 bg_import/dataplex-glossary/glossary_import.py

La utilidad de importación imprime el resultado de la ejecución de la API de CreateMetadataJob directamente en tu terminal. Verifica que el estado del trabajo indique que se completó correctamente.

Puedes revisar los registros de ejecución en el directorio logs/ de tu ruta de ejecución local. Estos registros te ayudan a auditar el proceso de transferencia y a identificar las entradas omitidas o las advertencias de formato.

¿Qué sigue?