Esegui la transizione al glossario aziendale in Knowledge Catalog

Questo documento fornisce istruzioni per la migrazione in un unico passaggio dalla versione di anteprima del glossario aziendale, che supportava i metadati di Data Catalog, alla versione in disponibilità generale del glossario aziendale in Knowledge Catalog (in precedenza Dataplex Universal Catalog). La migrazione alla versione in disponibilità generale ti consente di utilizzare le funzionalità avanzate e l'integrazione più approfondita con i metadati di Knowledge Catalog, offrendo maggiore stabilità, nuove funzionalità e supporto completo per la produzione. Questa procedura aggiorna automaticamente i glossari per supportare i metadati di Knowledge Catalog.

Nota: se hai già avviato la procedura di migrazione utilizzando la procedura manuale per la migrazione dei glossari e vuoi accedere a queste istruzioni, consulta Eseguire manualmente la transizione al glossario aziendale su Knowledge Catalog.

Prima di iniziare

1. Installa i pacchetti gcloud o Python. Autentica il tuo account utente e le Credenziali predefinite dell'applicazione (ADC) utilizzate dalle librerie Python. Esegui i seguenti comandi e segui le istruzioni basate sul browser:

   gcloud init
   gcloud auth login
   gcloud auth application-default login
   

2. Abilita le seguenti API:

   • API Dataplex
   • API Data Catalog
   • API Resource Manager
   • API Storage di Cloud

3. Crea uno o più bucket Cloud Storage in uno dei tuoi progetti. I bucket verranno utilizzati come posizione temporanea per i file di importazione. Più bucket fornisci, più veloce sarà l'importazione. Concedi il ruolo IAM Storage Admin al account di servizio che esegue la migrazione:

   [e-mail]

   Sostituisci MIGRATION_PROJECT_ID con il progetto da cui stai eseguendo la migrazione dei glossari.

4. Configura il repository:

   1. Clona il repository:

      git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
      cd dataplex-labs/dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import
      

   2. Installa i pacchetti richiesti:

      pip3 install -r requirements.txt
      cd migration
      

      Nota: se riscontri problemi durante l'installazione del pacchetto, segui i passaggi per creare un nuovo ambiente virtuale Python.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire la migrazione dei glossari da Data Catalog a Knowledge Catalog, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Proprietario glossari Data Catalog (roles/datacatalog.glossaryOwner) nel tuo progetto
• Dataplex Administrator (roles/dataplex.admin) nel tuo progetto

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

Questi ruoli predefiniti contengono le autorizzazioni necessarie per eseguire la migrazione dei glossari da Data Catalog a Knowledge Catalog. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per eseguire la migrazione dei glossari da Data Catalog a Knowledge Catalog sono necessarie le seguenti autorizzazioni:

• datacatalog.glossaries.get nel progetto da cui stai eseguendo la migrazione dei glossari
• datacatalog.glossaries.list nel progetto da cui stai eseguendo la migrazione dei glossari
• dataplex.glossaries.create nel progetto in cui vengono creati i glossari in Knowledge Catalog
• dataplex.glossaries.update nel progetto in cui verranno aggiornati i glossari in Knowledge Catalog

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Per saperne di più su Identity and Access Management (IAM) di Knowledge Catalog, consulta Gestire l'accesso con IAM.

Esegui lo script di migrazione

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2

Sostituisci quanto segue:

• USER_PROJECT_ID: l'ID progetto del progetto di cui eseguire la migrazione.

  MIGRATION_PROJECT_ID si riferisce al progetto di origine contenente i glossari di Data Catalog che vuoi esportare. USER_PROJECT_ID è il progetto utilizzato per l'attribuzione di fatturazione e quota per le chiamate API generate dallo script.

• BUCKET1 e BUCKET2: gli ID dei bucket Cloud Storage da utilizzare per l'importazione.

  Puoi fornire uno o più bucket. Per gli argomenti del bucket, fornisci un elenco separato da virgole di nomi di bucket senza spazi (ad esempio, --buckets=bucket-one,bucket-two). Non è richiesto un mapping one-to-one tra bucket e glossari; lo script esegue i job di importazione in parallelo, velocizzando la migrazione.

Se i problemi di autorizzazione impediscono allo script di rilevare automaticamente gli ID organizzazione, utilizza il flag --orgIds per specificare le organizzazioni che lo script può utilizzare per cercare gli asset di dati collegati ai termini del glossario.

Nota: non modificare i file JSON esportati. Lo script genera file nel formato richiesto dall'API di importazione di Dataplex; la modifica del formato può causare il mancato completamento dei job di importazione.

Definisci l'ambito dei glossari nella migrazione

Per eseguire la migrazione solo di glossari specifici, definisci il loro ambito fornendo i rispettivi URL.

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2 --glossaries="GLOSSARY_URL1","GLOSSARY_URL2"

Sostituisci GLOSSARY_URL1 (e GLOSSARY_URL2) con gli URL dei glossari di cui stai eseguendo la migrazione. Puoi fornire uno o più URL del glossario.

Quando viene eseguita la migrazione, il numero di job di importazione può essere inferiore al numero di glossari esportati. Ciò si verifica quando i glossari vuoti che non richiedono un job di importazione in background vengono creati direttamente.

Riprendi la migrazione per gli errori dei job di importazione

La presenza di file dopo la migrazione indica che alcuni job di importazione non sono riusciti. Per riprendere la migrazione, esegui il seguente comando:

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2 --resume-import

Se riscontri errori, esegui di nuovo il comando resume. Lo script elabora solo i file che non sono stati importati ed eliminati correttamente.

Lo script applica i controlli delle dipendenze per i link di voce e i link tra glossari. Un file di link di voce viene importato solo se il glossario principale è stato importato correttamente. Allo stesso modo, un link tra i termini viene importato solo se tutti i termini a cui viene fatto riferimento sono stati importati correttamente.

Nota: nei log o nei file generati potrebbero essere aggiunti ID casuali ai nomi di glossari, link di voci e job. Questi ID sono per l'unicità del backend interno e non influiscono sui nomi o sulla struttura dei glossari migrati finali.

Risoluzione dei problemi

Questa sezione fornisce soluzioni agli errori comuni.

• Errore Autorizzazione negata / 403: assicurati che l'utente o il account di servizio abbia il ruolo Editor Dataplex nel progetto di destinazione e il ruolo Visualizzatore Dataplex nel progetto di origine.

• ModuleNotFoundError: assicurati di aver attivato l'ambiente virtuale Python e di aver installato i pacchetti richiesti utilizzando pip3 install -r requirements.txt.

• TimeoutError / ssl.SSLError: questi errori a livello di rete potrebbero essere causati da firewall, proxy o connessioni lente. Lo script ha un timeout di 5 minuti. I problemi persistenti potrebbero richiedere il controllo della configurazione della rete locale.

• Metodo non trovato (Impossibile recuperare le voci): questo errore indica spesso che il tuo progetto utente non è incluso nell'elenco consentito per chiamare l'API, impedendo il recupero delle voci necessarie.