Importare i link alle voci da un foglio Google

Questo documento spiega come utilizzare l'utilità di importazione dei link delle voci per importare in blocco i link delle voci (relazioni tra i termini del glossario e gli asset di dati, inclusi i tipi di link delle voci definition, related e synonym) da un foglio Google in Knowledge Catalog (in precedenza Dataplex Universal Catalog).

Prima di iniziare

Prima di importare i link delle voci in Knowledge Catalog, completa i seguenti prerequisiti.

Configurare il account di servizio

Per eseguire l'utilità di importazione utilizzando Fogli 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 ulteriori informazioni, 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 ulteriori informazioni, 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 link delle voci 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 Gestisci 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 link delle voci, abilita le seguenti API nel tuo progetto:

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. 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
cd dataplex-glossary

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

Requisiti di importazione tra progetti

Per importare i link delle voci in più Google Cloud progetti, assicurati che la configurazione soddisfi i seguenti requisiti prima di eseguire l'utilità di importazione:

  • Configura le autorizzazioni IAM tra progetti: il account di servizio che esegue lo script di importazione deve disporre di autorizzazioni sufficienti in tutti i progetti di destinazione.

  • Verifica l'esistenza delle voci: le voci di destinazione devono già esistere nei rispettivi progetti Knowledge Catalog prima di eseguire l'importazione.

  • Concedi l'accesso al bucket Cloud Storage ai service agent di Knowledge Catalog: i service account di Knowledge Catalog in ogni progetto di destinazione richiedono l'accesso ai bucket Cloud Storage.

Crea e struttura il foglio Google per l'importazione

Per eseguire correttamente un'importazione in blocco, 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:

Intestazione di colonna Obbligatorio o facoltativo Descrizione
entry_link_type Obbligatorio Il valore deve essere definition, related o synonym.
source_entry Obbligatorio Il percorso completo della risorsa della voce di origine nel formato:
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
target_entry Obbligatorio Il percorso completo della risorsa della voce di destinazione nel formato:
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
source_path Facoltativo Percorso di colonna o campo per i link di definizione (ad esempio, Schema.column_name).

Imposta le variabili di ambiente

Imposta le seguenti variabili di ambiente:

# 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 i link delle voci dal foglio Google

Per importare i link delle voci dal foglio Google in Knowledge Catalog, esegui lo script entrylinks-import.py:

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

Per eseguire più job di importazione in parallelo, specifica più bucket Cloud Storage nel parametro --buckets. Lo script suddivide i metadati in batch più piccoli e li elabora contemporaneamente nei bucket, riducendo il tempo totale di importazione.

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 ignorate o gli avvisi di formattazione.

Passaggi successivi