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 de prévia do glossário empresarial, que oferecia suporte a metadados do Data Catalog, para a versão disponível publicamente do glossário empresarial, que oferece suporte a metadados do Knowledge Catalog (antigo Dataplex Universal Catalog). O processo de transição inclui a exportação de glossários, categorias, termos e links do Data Catalog e a importação deles para o Knowledge Catalog.

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

  1. Exportar glossários e links de entrada do Data Catalog.
  2. Importar 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 este formulário.

Instale os pacotes Python ou gcloud.

Funções exigidas

Para exportar um glossário do Data Catalog, é necessário ter a função 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 empresarial para o Knowledge Catalog, peça ao administrador para conceder a você a função 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 que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para importar o glossário empresarial para o Knowledge Catalog:

  • dataplex.glossaries.import no recurso do glossário
  • dataplex.entryGroups.import no grupo de entradas do Knowledge Catalog fornecido no campo entry_groups e nos grupos de entradas em que as entradas do Data Catalog estão presentes e vinculadas aos termos do glossário
  • dataplex.entryGroups.useSynonymEntryLink no grupo de entradas do Knowledge Catalog fornecido no campo entry_groups e nos grupos de entradas em que as entradas do Data Catalog estão presentes e vinculadas aos termos do glossário
  • dataplex.entryGroups.useRelatedEntryLink no grupo de entradas do Knowledge Catalog fornecido no campo entry_groups e nos grupos de entradas em que as entradas do Data Catalog estão presentes e vinculadas aos termos do glossário
  • dataplex.entryLinks.reference em todos os projetos fornecidos no campo referenced_entry_scopes

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 \
--user-project="PROJECT_ID" \
--url="DATA_CATALOG_GLOSSARY_URL"

    Substitua:

    • PROJECT_ID: o ID do projeto que contém o glossário.
    • DATA_CATALOG_GLOSSARY_URL: o URL do glossário empresarial do Data Catalog no Google Cloud console.

    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
    • Termo: 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 valores de GLOSSARY_ID, CATEGORY_ID, TERM_ID, PROJECT_ID e LOCATION_ID são os mesmos do glossário do Data Catalog.

Resultados

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

  • Os glossários e as categorias e termos deles 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 os 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 após a execução do script de exportação.

Importar glossários, categorias e termos

É necessário importar os glossários, categorias e termos do Knowledge Catalog 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 depois 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 metadataJobs.get método:

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

    Se você receber 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 para o bucket.

  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 a glossários em projetos diferentes, forneça o ID do projeto
    • Opcional: LINKED_GLOSSARY_PROJECT_ID_2: se os termos estiverem vinculados a glossários em 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 que o glossário.

    • O objeto entry_link_types permite 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 de links de entrada que vinculam termos de glossários diferentes.

Importar links entre termos e colunas

É necessário importar os links entre termos e colunas exportados na etapa anterior. Esta seção descreve 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 de entradas.

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