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

Este documento fornece instruções para migrar em uma única etapa da versão de prévia do glossário de negócios, que oferecia suporte a metadados do Data Catalog, para a versão de disponibilidade geral do glossário de negócios no Dataplex Universal Catalog. A migração para a versão disponível permite usar os recursos aprimorados e a integração mais profunda com os metadados do Dataplex Universal Catalog, oferecendo estabilidade aprimorada, novos recursos e suporte total à produção. Esse processo atualiza automaticamente seus glossários para oferecer suporte aos metadados do Dataplex Universal Catalog.

Observação: se você já iniciou o processo de migração usando o método manual para migrar seus glossários e quer acessar essas instruções, consulte Fazer a transição manual para o glossário de negócios no Dataplex Universal Catalog.

Antes de começar

1. Instale gcloud ou pacotes Python. Autentique sua conta de usuário e o Application Default Credentials (ADC) usado 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 Cloud Resource Manager
   • API Cloud Storage

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 do IAM de administrador do Storage à conta de serviço que está executando a migração:

   [e-mail]

   Substitua MIGRATION_PROJECT_ID pelo projeto de onde 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 do Python.

Funções exigidas

Para receber as permissões necessárias para migrar glossários do Data Catalog para o Catálogo universal do Dataplex, 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 catálogo universal do Dataplex. Para acessar as permissões exatas 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 Dataplex Universal Catalog:

• datacatalog.glossaries.get no projeto de origem dos glossários
• datacatalog.glossaries.list no projeto de origem dos glossários
• dataplex.glossaries.create no projeto em que os glossários são criados no Dataplex Universal Catalog
• dataplex.glossaries.update no projeto em que os glossários serão atualizados no Dataplex Universal Catalog

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

Para mais informações sobre Identity and Access Management (IAM) do Dataplex Universal Catalog, consulte Controle de 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 intervalos. Para os argumentos de bucket, forneça uma lista separada por vírgulas de nomes de bucket 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 Universal Catalog. Modificar o formato pode causar falhas nos jobs de importação.

Escopo dos glossários 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 uma tarefa de importação em segundo plano são criados diretamente.

Retomar a migração em caso de falhas no 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 houver 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 entre glossários. Um arquivo de link de entrada só é importado se o glossário principal foi importado com sucesso. 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 nos registros ou arquivos gerados. Esses IDs são para exclusividade interna de back-end e não afetam os nomes ou a estrutura dos glossários migrados finais.

Resolver problemas

Esta seção oferece 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 Universal Catalog no projeto de destino e o papel de visualizador do Data Catalog no projeto de origem.

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

• TimeoutError / ssl.SSLError: esses erros no nível da 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 seu projeto de usuário não está na lista de permissões para chamar a API, impedindo a recuperação das entradas necessárias.