Fazer a transição manual para o glossário empresarial no Catálogo de Conhecimento

Este documento fornece instruções para migrar da versão prévia do glossário de negócios, que oferecia suporte a metadados do Data Catalog, para a versão de disponibilidade geral, que oferece suporte a metadados do Knowledge Catalog (antigo Dataplex Universal Catalog). O processo de transição inclui exportar glossários, categorias, termos e links do Data Catalog e importá-los para o Knowledge Catalog.

Para fazer a transição manual para o glossário empresarial no Knowledge Catalog, siga estas etapas:

1. Exportar glossários e links de entrada do Data Catalog.
2. Importe glossários, categorias e termos para o Knowledge Catalog.
3. Importar links entre termos para o Knowledge Catalog.
4. Importar links entre termos e colunas para o Knowledge Catalog.

Antes de começar

Para ativar a exportação de glossários no Data Catalog, inscreva-se usando o formulário de inscrição.

Instale gcloud ou pacotes Python.

Funções exigidas

Para exportar um glossário do Data Catalog, você precisa ter o papel roles/datacatalog.glossaryOwner nos projetos em que o glossário está presente. Consulte as permissões necessárias para essa função.

Para receber as permissões necessárias para importar o glossário de negócios para o catálogo do Knowledge, peça ao administrador para conceder a você o papel de Administrador do Dataplex (roles/dataplex.admin) do IAM nos projetos. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para importar o glossário empresarial para o Knowledge Catalog. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Exportar glossários, categorias e termos do Data Catalog

É possível exportar um glossário por vez.

1. Clone o repositório dataplex-labs e mude os diretórios para o subdiretório business-glossary-import:

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

2. Receba seu token de acesso:

   export GCLOUD_ACCESS_TOKEN=$(gcloud auth print-access-token)
   

3. Execute o script de exportação:

   python3 bg_import/business_glossary_export_v2.py \
   --project="PROJECT_ID" \
   --url="DATA_CATALOG_GLOSSARY_URL"

   Substitua:

   • PROJECT_ID: o ID do projeto que contém o glossário. Esse projeto também é usado para faturamento e cota.
   • DATA_CATALOG_GLOSSARY_URL: o URL completo do glossário empresarial do Data Catalog, conforme aparece no consoleGoogle Cloud .

   Exemplo: https://console.cloud.google.com/datacatalog/glossaries/projects/my-project/locations/us-central1/entryGroups/my-entry-group/glossaries/my-glossary

   O script cria um arquivo JSON que segue o mesmo formato do arquivo de importação de metadados usado para jobs de importação de metadados. Os nomes do glossário, das categorias e dos termos usam os seguintes formatos:

   • Glossário: projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/{PROJECT_ID{"</var>"}}/locations/LOCATION_ID/glossaries/GLOSSARY_ID
   • Período: projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM_ID
   • Categoria: projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID

   Os tokens GLOSSARY_ID, CATEGORY_ID, TERM_ID, PROJECT_ID e LOCATION_ID são iguais aos valores do glossário do Data Catalog.

Resultados

A lista a seguir descreve alguns pontos importantes sobre os resultados:

• Os glossários, as categorias e os termos são exportados em um local global, o que permite que os termos sejam vinculados a uma entrada em qualquer região.

• Os arquivos exportados estão na pasta Exported_Files em dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import. O nome do arquivo é glossary_GLOSSARY_ID.json.

• O comando de exportação cria automaticamente o glossário no Knowledge Catalog com o mesmo GLOSSARY_ID e PROJECT_ID no local global.

• O script cria um arquivo JSON que contém os sinônimos e links relacionados entre os termos. Os arquivos exportados estão na pasta "Exported_Files" em dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import. O nome do arquivo é entrylinks_related_synonym_GLOSSARY_ID.json.

• Os links exportados estão na pasta Exported_Files em dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import.

• Os termos em um glossário podem ser vinculados a muitas entradas em muitos grupos de entradas. A exportação de links entre termos e colunas cria um arquivo para cada entryGroup. O formato do nome do arquivo é: entrylinks_definition_export_GLOSSARY_ID_ENTRY_PROJECT_ID_ENTRY_LOCATION_ID_ENTRY_GROUP_ID.json.

• O ID do glossário necessário para importar glossários, categorias e termos aparece depois que o script de exportação é executado.

Importar glossários, categorias e termos

É necessário importar os glossários, categorias e termos do Knowledge Catalog exportados na etapa anterior. Nesta seção, descrevemos como importar usando a API de job de metadados.

1. Crie um bucket do Cloud Storage e faça upload do arquivo para ele.

2. Conceda à conta de serviço do Knowledge Catalog acesso de leitura ao bucket do Cloud Storage.

3. Execute um job de importação de metadados para importar o glossário.

   # Set GCURL alias
   alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

   # Import CURL Command
   gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs\?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -d "$(cat<<EOF
   {
   "type":"IMPORT",
   "import_spec":{
       "log_level": "DEBUG",
       "source_storage_uri": "gs://STORAGE_BUCKET/",
       "entry_sync_mode": "FULL",
       "aspect_sync_mode": "INCREMENTAL",
       "scope": {
         "glossaries": ["projects/PROJECT_ID/locations/global/glossaries/GLOSSARY_ID"]
       }
   }
   }
   EOF
   )"

   Substitua:

   • JOB_ID: (opcional) um ID de job de importação de metadados, que pode ser usado para acompanhar o status do job. Se você não fornecer um ID, o comando gcurl vai gerar um ID exclusivo.
   • STORAGE_BUCKET: o URI do bucket ou da pasta do Cloud Storage que contém o arquivo de glossário exportado.
   • PROJECT_ID: o número do projeto que contém o glossário.

4. Opcional: para acompanhar o status do job de importação de metadados, use o método metadataJobs.get:

   gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs/JOB_ID

   Se houver erros no job de importação de metadados, eles vão aparecer nos registros.

Importar links entre termos para o Knowledge Catalog

É necessário importar os links entre os termos exportados na etapa anterior. Esta seção descreve como importar usando a API de job de metadados.

1. Crie um bucket do Cloud Storage e faça upload do arquivo de links de entrada exportado da etapa anterior.

2. Conceda à conta de serviço do Knowledge Catalog acesso de leitura ao bucket do Cloud Storage.

3. Execute um job de importação de metadados para importar os links de entrada:

   # Import CURL Command
   gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -d "$(cat<<EOF
   {
   "type": "IMPORT",
   "import_spec": {
     "log_level": "DEBUG",
     "source_storage_uri": "gs://STORAGE_BUCKET/",
     "entry_sync_mode": "FULL",
     "aspect_sync_mode": "INCREMENTAL",
     "scope": {
       "entry_groups": ["projects/GLOSSARY_PROJECT_ID/locations/global/entryGroups/@dataplex"],
       "entry_link_types": [
         "projects/dataplex-types/locations/global/entryLinkTypes/synonym",
         "projects/dataplex-types/locations/global/entryLinkTypes/related"
       ],
       "referenced_entry_scopes": ["projects/GLOSSARY_PROJECT_ID","projects/LINKED_GLOSSARY_PROJECT_ID_1","projects/LINKED_GLOSSARY_PROJECT_ID_2"]
     }
   }
   }
   EOF
   )"

   Substitua:

   • GLOSSARY_PROJECT_ID: o ID do projeto que contém o glossário
   • Opcional: LINKED_GLOSSARY_PROJECT_ID_1: se os termos estiverem vinculados em glossários de projetos diferentes, forneça o ID do projeto.
   • Opcional: LINKED_GLOSSARY_PROJECT_ID_2: se os termos estiverem vinculados em glossários de projetos diferentes, forneça o ID do projeto.

   Observe o seguinte:

   • O objeto entry_groups contém o grupo de entradas em que os links de entrada são criados. Esse é o grupo de entradas do sistema @dataplex no mesmo projeto e local do glossário.

   • Com o objeto entry_link_types, é possível importar sinônimos, termos relacionados ou ambos:

     • Sinônimos: projects/dataplex-types/locations/global/entryLinkTypes/synonym
     • Termos relacionados: projects/dataplex-types/locations/global/entryLinkTypes/related

   • O objeto referenced_entry_scopes inclui os IDs de projeto dos links de entrada que vinculam termos de diferentes glossários.

Importar links entre termos e colunas

É necessário importar os links entre os termos e as colunas exportados na etapa anterior. Nesta seção, descrevemos como importar usando a API de job de metadados.

1. Faça upload de cada arquivo exportado na etapa anterior para um bucket do Cloud Storage.

2. Execute um comando de importação separado para cada arquivo enviado por upload no bucket do Cloud Storage. Cada arquivo corresponde a um grupo de entradas exclusivo que contém links entre termos e colunas desse grupo.

gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/metadataJobs?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -d "$(cat<<EOF
{
"type": "IMPORT",
"import_spec": {
    "log_level": "DEBUG",
    "source_storage_uri": "gs://STORAGE_BUCKET/",
    "entry_sync_mode": "FULL",
    "aspect_sync_mode": "INCREMENTAL",
    "scope": {
        "entry_groups": ["projects/ENTRY_GROUP_PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/entryGroups/ENTRY_GROUP_ID"],
        "entry_link_types": ["projects/dataplex-types/locations/global/entryLinkTypes/definition"],
        "referenced_entry_scopes": ["projects/ENTRY_GROUP_PROJECT_ID", "projects/GLOSSARY_PROJECT_ID"]
    }
}
}
EOF
)"

A seguir

• Gerenciar um glossário empresarial no Knowledge Catalog
• Transição para o Knowledge Catalog