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 realizar la importación masiva de 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 Knowledge Catalog CreateMetadataJob, 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 Google Sheets 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 la identidad temporal como cuenta de servicio.

    Para ejecutar la secuencia de comandos de la utilidad de importación de forma local, tu cuenta de usuario debe tener permiso para suplantar la cuenta de servicio. En tu cuenta de servicio, otorga a tu cuenta de usuario el rol de creador de tokens de cuentas de servicio (roles/iam.serviceAccountTokenCreator).

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

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

    Abre la hoja de cálculo de Google que deseas 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 sirva como área de preparación 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 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 permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén 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 identidad temporal como cuenta de servicio

Inicializa Google Cloud CLI y autentica con las credenciales predeterminadas de la aplicación (ADC) con la identidad temporal como 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 hoja de cálculo de Google nueva 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 de 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 Un identificador único para el término o la categoría dentro del glosario.
parent Opcional El ID de la categoría superior. Si está vacío, el elemento es un elemento secundario de nivel raíz del glosario. Ten en cuenta que el ID superior al que se hace referencia debe existir en la hoja y pertenecer a una categoría.
display_name Obligatorio El nombre visible del término o la categoría.
description Opcional Una breve descripción del término o la categoría.
overview Opcional Una descripción de texto enriquecido del término o la categoría (admite etiquetas HTML).
type Obligatorio 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 para el término o la categoría.
contact1_name Opcional Nombre del administrador de datos principal para el 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 para el término o la categoría.
label1_key Opcional Clave de la primera etiqueta asignada.
label1_value Opcional Valor de la primera etiqueta asignada.
label2_key Opcional Clave de la segunda etiqueta asignada.
label2_value Opcional Valor de la segunda etiqueta asignada.

Importa el glosario desde 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 realizó 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?