Importare glossari aziendali da un foglio Google

Questo documento spiega come utilizzare l'utilità di importazione del glossario per eseguire l'importazione collettiva di glossari, categorie e termini da un foglio Google in Knowledge Catalog (in precedenza Dataplex Universal Catalog).

L'glossary_import utility analizza e convalida i dati di un foglio Google, li converte in un formato compatibile con l'API CreateMetadataJob di Knowledge Catalog, e li carica in un bucket Cloud Storage prima di attivare il job di importazione.

Prima di iniziare

Prima di importare i glossari, completa i seguenti prerequisiti.

Configurare il account di servizio

Per eseguire l'utilità di importazione utilizzando un foglio Google, devi configurare un service account con le autorizzazioni necessarie per accedere all'API Google Sheets e simulare le credenziali utente:

  1. Identifica o crea un account di servizio.

    Seleziona un account di servizio esistente o creane uno nuovo nel progetto in cui esegui l'utilità di importazione. Per saperne di più, consulta Creare service account. Prendi nota dell'indirizzo email del account di servizio (ad esempio, SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com).

  2. Configura la simulazione dell'identità del account di servizio.

    Per eseguire lo script dell'utilità di importazione in locale, il tuo account utente deve disporre dell'autorizzazione per simulare l'identità del account di servizio. Concedi al tuo account utente il ruolo Creatore token account di servizio (roles/iam.serviceAccountTokenCreator) nel service account.

    Per saperne di più, consulta Gestire l'accesso ai service account.

  3. Concedi al account di servizio l'accesso Editor al foglio Google.

    Apri il foglio Google che vuoi utilizzare per la procedura di importazione, fai clic su Condividi, e aggiungi l'indirizzo email del account di servizio come Editor. Questa autorizzazione consente al account di servizio di leggere o scrivere dati nel foglio.

Crea un bucket Cloud Storage

Crea un bucket Cloud Storage da utilizzare come area di gestione temporanea per i file di importazione.

Ruoli obbligatori

Per assicurarti che il account di servizio disponga delle autorizzazioni necessarie per importare i glossari da un foglio Google, chiedi all'amministratore di concedere i seguenti ruoli IAM al account di servizio:

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

L'amministratore potrebbe anche assegnare al account di servizio le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

Abilita API

Per importare i glossari, abilita le seguenti API nel tuo progetto:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

Configura il repository Git

Clona il repository 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

Installa le dipendenze

Installa le dipendenze Python richieste:

pip3 install -r requirements.txt

Se riscontri problemi con l'installazione del pacchetto, configura un nuovo ambiente di sviluppo Python.

Autentica e configura la simulazione dell'identità del account di servizio

Inizializza Google Cloud CLI ed esegui l'autenticazione utilizzando le credenziali predefinite dell'applicazione (ADC) con la simulazione dell'identità del account di servizio:

# 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"

Sostituisci SERVICE_ACCOUNT_EMAIL con l'ID email del account di servizio. Ad esempio:

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Crea e struttura il foglio Google per l'importazione

Per eseguire correttamente un'importazione collettiva, devi creare un nuovo foglio Google utilizzando uno schema di colonne preciso in modo che l'utilità di importazione possa analizzare e convalidare correttamente i campi dei metadati. Assicurati di aver concesso al account di servizio l'accesso Editor al foglio Google.

La prima riga del foglio deve contenere queste intestazioni di schema esatte e sensibili alle maiuscole/minuscole:

Campo Obbligatorio o facoltativo Descrizione
id Obbligatorio Un identificatore univoco per il termine o la categoria all'interno del glossario.
parent Facoltativo L'ID della categoria principale. Se è vuoto, l'elemento è un elemento secondario di primo livello del glossario. Tieni presente che l'ID principale a cui viene fatto riferimento deve esistere nel foglio e deve appartenere a una categoria.
display_name Obbligatorio Il nome visualizzato del termine o della categoria.
description Facoltativo Una breve descrizione del termine o della categoria.
overview Facoltativo Una descrizione in Rich Text del termine o della categoria (supporta i tag HTML).
type Obbligatorio Il tipo di riga. I valori validi sono TERM o CATEGORY.
contact1_email Facoltativo Indirizzo email del responsabile dei dati principale per il termine o la categoria.
contact1_name Facoltativo Nome del responsabile dei dati principale per il termine o la categoria.
contact2_email Facoltativo Indirizzo email del responsabile dei dati secondario per il termine o la categoria.
contact2_name Facoltativo Nome del responsabile dei dati secondario per il termine o la categoria.
label1_key Facoltativo Chiave per la prima etichetta assegnata.
label1_value Facoltativo Valore per la prima etichetta assegnata.
label2_key Facoltativo Chiave per la seconda etichetta assegnata.
label2_value Facoltativo Valore per la seconda etichetta assegnata.

Importa il glossario dal foglio Google

Dopo aver configurato l'ambiente e preparato il foglio Google, esegui lo script glossary_import.py:

python3 bg_import/dataplex-glossary/glossary_import.py

L'utilità di importazione stampa il risultato dell'esecuzione dell'API CreateMetadataJob direttamente nel terminale. Verifica che lo stato del job indichi che l'operazione è riuscita.

Puoi esaminare i log di esecuzione nella directory logs/ nel percorso di esecuzione locale. Questi log ti aiutano a controllare la procedura di trasferimento e a identificare le voci saltate o gli avvisi di formattazione.

Passaggi successivi