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

Este documento fornece instruções para migrar em uma única etapa da versão de pré-lançamento do glossário empresarial, que oferecia suporte a metadados do Data Catalog, para a versão de disponibilidade geral do glossário empresarial no Knowledge Catalog (antigo Dataplex Universal Catalog). A migração para a versão de disponibilidade geral permite usar os recursos aprimorados e a integração mais profunda com os metadados do Knowledge Catalog, oferecendo maior estabilidade, novos recursos e suporte de produção completo. Esse processo atualiza automaticamente seus glossários para oferecer suporte a metadados do Knowledge Catalog.

Observação: Se você já iniciou o processo de migração usando o processo manual para migrar seus glossários e quer acessar essas instruções, consulte Fazer a transição manual para o glossário empresarial no Knowledge Catalog.

Antes de começar

1. Instale os pacotes gcloud ou Python. Autentique sua conta de usuário e as Application Default Credentials (ADC) usadas pelas bibliotecas Python. Execute os comandos a seguir e siga as instruções baseadas no navegador:

   gcloud init
   gcloud auth login
   gcloud auth application-default login
   

2. Ative as APIs a seguir:

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

3. Crie um ou vários buckets do Cloud Storage em qualquer um dos seus projetos. Os buckets serão usados como um local temporário para os arquivos de importação. Quanto mais buckets você fornecer, mais rápida será a importação. Conceda o papel de IAM do Storage Admin à conta de serviço que executa a migração:

   [e-mail]

   Substitua MIGRATION_PROJECT_ID pelo projeto do qual você está migrando os glossários.

4. Configure o repositório:

   1. Clone o repositório:

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

   2. Instale os pacotes necessários.

      pip3 install -r requirements.txt
      cd migration
      

      Observação: se você tiver problemas para instalar o pacote, siga as etapas para criar um novo ambiente virtual Python.

Funções exigidas

Para receber as permissões necessárias para migrar glossários do Data Catalog para o Knowledge Catalog, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Proprietário do glossário do Data Catalog (roles/datacatalog.glossaryOwner) no seu projeto
• Administrador do Dataplex (roles/dataplex.admin) no seu projeto

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para migrar glossários do Data Catalog 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 migrar glossários do Data Catalog para o Knowledge Catalog:

• datacatalog.glossaries.get no projeto do qual você está migrando glossários
• datacatalog.glossaries.list no projeto do qual você está migrando glossários
• dataplex.glossaries.create no projeto em que os glossários são criados no Knowledge Catalog
• dataplex.glossaries.update no projeto em que os glossários serão atualizados no Knowledge Catalog

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

Para mais informações sobre o Identity and Access Management (IAM) do Knowledge Catalog, consulte Gerenciar o acesso com o IAM.

Executar o script de migração

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

Substitua:

• USER_PROJECT_ID: o ID do projeto a ser migrado.

  O MIGRATION_PROJECT_ID se refere ao projeto de origem que contém os glossários do Data Catalog que você quer exportar. O USER_PROJECT_ID é o projeto usado para faturamento e atribuição de cota para as chamadas de API geradas pelo script.

• BUCKET1 e BUCKET2: os IDs bucket do Cloud Storage a serem usados para a importação.

  É possível fornecer um ou mais buckets. Para os argumentos do bucket, forneça uma lista separada por vírgulas de nomes de buckets sem espaços (por exemplo, --buckets=bucket-one,bucket-two). Não é necessário um mapeamento um para um entre buckets e glossários. O script executa os jobs de importação em paralelo, acelerando a migração.

Se problemas de permissão impedirem que o script descubra automaticamente os IDs da sua organização, use a flag --orgIds para especificar as organizações que o script pode usar para pesquisar recursos de dados vinculados a termos do glossário.

Observação: não edite os arquivos JSON exportados. O script gera arquivos no formato exigido pela API de importação do Dataplex. A modificação do formato pode causar falhas nos jobs de importação.

Glossários de escopo na migração

Para migrar apenas glossários específicos, defina o escopo deles fornecendo os respectivos URLs.

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

Substitua GLOSSARY_URL1 (e GLOSSARY_URL2) pelos URLs dos glossários que você está migrando. É possível fornecer um ou mais URLs de glossário.

Quando a migração é executada, o número de jobs de importação pode ser menor que o número de glossários exportados. Isso acontece quando glossários vazios que não exigem um job de importação em segundo plano são criados diretamente.

Retomar a migração para falhas de job de importação

A presença de arquivos após a migração indica que alguns jobs de importação falharam. Para retomar a migração, execute o seguinte comando:

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

Se você encontrar falhas, execute o comando resume novamente. O script processa apenas arquivos que não foram importados e excluídos.

O script aplica verificações de dependência para links de entrada e links entre glossários. Um arquivo de link de entrada só é importado se o glossário pai tiver sido importado. Da mesma forma, um link entre termos só é importado se todos os termos referenciados tiverem sido importados.

Observação: IDs aleatórios podem ser anexados a glossários, links de entrada e nomes de jobs em registros ou arquivos gerados. Esses IDs são para exclusividade de back-end interno e não afetam os nomes ou a estrutura dos glossários migrados finais.

Resolver problemas

Esta seção fornece soluções para erros comuns.

• Permissão negada / erro 403: verifique se o usuário ou a conta de serviço tem o papel de editor do Dataplex no projeto de destino e o papel de leitor do Dataplex no projeto de origem.

• ModuleNotFoundError: verifique se você ativou seu ambiente virtual Python e instalou os pacotes necessários usando pip3 install -r requirements.txt.

• TimeoutError / ssl.SSLError: esses erros de nível de rede podem ser causados por firewalls, proxies ou conexões lentas. O script tem um tempo limite de 5 minutos. Problemas persistentes podem exigir a verificação da configuração da rede local.

• Método não encontrado (não é possível buscar entradas): esse erro geralmente indica que o projeto do usuário não está na lista de permissões para chamar a API, impedindo a recuperação das entradas necessárias.