Importa vínculos de entrada desde una hoja de cálculo de Google

En este documento, se explica cómo usar la utilidad de importación de vínculos de entrada para importar de forma masiva vínculos de entrada (relaciones entre términos del glosario y recursos de datos, incluidos los tipos de vínculos de entrada definition, related y synonym) desde una Hoja de cálculo de Google a Knowledge Catalog (anteriormente, Dataplex Universal Catalog).

Antes de comenzar

Antes de importar vínculos de entrada a Knowledge Catalog, completa los siguientes requisitos previos.

Configura la cuenta de servicio

Para ejecutar la utilidad de importación con Hojas 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 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 vínculos de entrada 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 vínculos de entrada, 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
cd dataplex-glossary

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 init
gcloud auth login
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

Requisitos para la importación entre proyectos

Para importar vínculos de entrada en varios proyectos de Google Cloud , asegúrate de que tu configuración cumpla con los siguientes requisitos antes de ejecutar la utilidad de importación:

  • Configura permisos de IAM entre proyectos: La cuenta de servicio que ejecuta la secuencia de comandos de importación debe tener permisos suficientes en todos los proyectos de destino.

  • Verifica la existencia de la entrada: Las entradas de destino ya deben existir en sus respectivos proyectos de Knowledge Catalog antes de que ejecutes la importación.

  • Otorga acceso a los bucket de Cloud Storage a los agentes de servicio de Knowledge Catalog: Las cuentas de servicio de Knowledge Catalog en cada proyecto de destino requieren acceso a tus buckets de Cloud Storage.

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:

Encabezado de columna Obligatorio u opcional Descripción
entry_link_type Obligatorio El valor debe ser definition, related o synonym.
source_entry Obligatorio Es la ruta de acceso completa del recurso de la entrada de origen con el siguiente formato:
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
target_entry Obligatorio Es la ruta de acceso completa del recurso de la entrada de destino en el siguiente formato:
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
source_path Opcional Es la ruta de acceso a la columna o el campo para los vínculos de definición (por ejemplo, Schema.column_name).

Configura variables de entorno

Configura las siguientes variables de entorno:

# Set your Google Sheet URL
export SPREADSHEET_URL="GOOGLE_SHEET_URL"

# Set your bucket name
export BUCKETS="COMMA_SEPARATED_LIST_OF_BUCKETS"

# Set the project ID
export USER_PROJECT="USER_PROJECT"

Importa vínculos de entrada desde la hoja de cálculo de Google

Para importar los vínculos de entrada de la hoja de cálculo de Google a Knowledge Catalog, ejecuta la secuencia de comandos entrylinks-import.py:

cd import
python3 entrylinks-import.py \
  --spreadsheet-url="$SPREADSHEET_URL" \
  --buckets="$BUCKETS" \
  --user-project="$USER_PROJECT"

Para ejecutar varios trabajos de importación en paralelo, especifica varios buckets de Cloud Storage en el parámetro --buckets. La secuencia de comandos divide los metadatos en lotes más pequeños y los procesa de forma simultánea en todos los buckets, lo que reduce el tiempo total de transferencia.

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?