Fazer a transição manual para o glossário de negócios no Dataplex Universal Catalog

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

Para fazer a transição manual para o glossário de negócios no Dataplex Universal Catalog, siga estas etapas:

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

Antes de começar

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

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 Dataplex Universal Catalog, peça ao administrador para conceder a você o papel do IAM de Administrador do Dataplex (roles/dataplex.admin) 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 de negócios para o Dataplex Universal Catalog. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para importar o glossário de negócios para o Dataplex Universal Catalog:

  • dataplex.glossaries.import no recurso de glossário
  • dataplex.entryGroups.import no grupo de entrada do Dataplex Universal Catalog fornecido no campo entry_groups e nos grupos de entrada em que as entradas do Data Catalog estão presentes e vinculadas aos termos do glossário
  • dataplex.entryGroups.useSynonymEntryLink no grupo de entrada do Dataplex Universal Catalog fornecido no campo entry_groups e nos grupos de entrada em que as entradas do Data Catalog estão presentes e vinculadas aos termos do glossário
  • dataplex.entryGroups.useRelatedEntryLink no grupo de entrada do Dataplex Universal Catalog fornecido no campo entry_groups e nos grupos de entrada 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 de negócios do Data Catalog no console do Google Cloud .

    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 para 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 Dataplex Universal 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 vários 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, as categorias e os termos do Dataplex Universal 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 Dataplex Universal 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 Dataplex Universal Catalog

É necessário importar os links entre os termos exportados na etapa anterior. Esta seção descreve como importar usando a API de jobs 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 Dataplex Universal 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 vínculos de entrada são criados. Esse é o grupo de entrada 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 diferentes glossários.

Importar links entre termos e colunas

É necessário importar os links entre termos e 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 ao 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