Resolver problemas com erros na importação de glossário empresarial e links de entradas

O Knowledge Catalog (antigo Dataplex Universal Catalog) permite importar e exportar glossários empresariais e links de entrada em massa para gerenciar seu vocabulário empresarial em grande escala. Ao executar os scripts do utilitário de importação ou exportação, é possível diagnosticar e resolver problemas comuns, como links de entrada ausentes, exportações de glossário vazias, URLs de glossário ou planilha inválidos, jobs de importação interrompidos e tempos limite de rede de script. Para mais informações, consulte Sobre como importar e exportar glossários e links de entrada.

Se precisar de ajuda para resolver um problema que não é abordado neste documento, consulte o Cloud Customer Care.

Corrigir links de entrada ausentes no Knowledge Catalog

Depois de exportar links de entrada do Knowledge Catalog para uma planilha do Google executando o utilitário de exportação de links de entrada, você percebe que alguns links de entrada (associações) estão ausentes na planilha do Google gerada.

Esse problema ocorre se o utilitário de exportação pular automaticamente os links de entrada devido às seguintes condições:

• Permissões insuficientes (recursos editados): você não tem as permissões do IAM necessárias para visualizar a entrada de origem ou de destino associada ao link.

• Tipo de link de entrada inválido: o link de entrada usa um tipo de relacionamento não compatível ou não reconhecido. Os tipos válidos são limitados a definition, related e synonym.

• Referências de entrada incompletas: os metadados de entrada não têm campos de esquema obrigatórios, o que faz com que a verificação de validação pule o recurso.

Para resolver esse problema, faça as seguintes verificações:

• Verifique as permissões: confira se você tem permissão para visualizar links de entrada ausentes. Confirme se o principal que está executando o script recebeu os papéis necessários.

• Inspecione os registros de execução: verifique se há avisos contendo Skipping redacted entrylink nos registros do terminal ou do script. Os registros mostram os IDs de recurso específicos dos links de entrada ignorados e o motivo da omissão.

• Verifique a validade do esquema de vinculação: se você modificou essas vinculações de forma programática, verifique se as propriedades delas correspondem aos requisitos do esquema.

Erro: nenhum termo encontrado no glossário

Quando você exporta glossários para uma planilha Google, a execução falha ou retorna um resultado vazio com a mensagem No terms found in the glossary, mesmo que o glossário empresarial contenha termos ativos.

Esse problema ocorre quando o script não consegue localizar o glossário especificado ou não tem as permissões de acesso necessárias para recuperar o conteúdo dele. Estas são as causas mais comuns:

• URL do glossário incorreto: o URL do glossário configurado nos parâmetros de execução está incorreto ou com erros de ortografia.
• Permissões insuficientes do IAM: a conta de serviço autenticada ou as credenciais de usuário que executam o script não têm permissão para visualizar ou listar termos no glossário de destino.
• Incompatibilidade de ID do glossário: o ID do glossário especificado no comando do script não corresponde ao ID do recurso do glossário real no Knowledge Catalog.

Para resolver esse problema, verifique sua configuração e permissões:

• Verifique o ID do glossário: no console do Google Cloud , acesse a página Glossários do Knowledge Catalog, selecione seu glossário e confirme se o ID do recurso corresponde ao ID que você está transmitindo para o script do utilitário.

• Verifique as permissões do IAM: confirme se as credenciais autenticadas (a conta de serviço ou a conta de usuário personificada) receberam os papéis necessários.

• Valide a estrutura do URL do glossário: se você estiver transmitindo um caminho de recurso direto ou um URL para o script, verifique se ele segue o formato de recurso correto do Knowledge Catalog:

  projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID

Aviso de entradas não encontradas no Knowledge Catalog

Durante uma operação de importação de link de entrada, o script é pausado e exibe um aviso semelhante ao seguinte:

Found X entries not found in Knowledge Catalog. EntryLinks associated with
these entries will be skipped. Continue with import? [y/N]:

Esse problema ocorre se o arquivo do Google Planilhas tiver links de entrada que fazem referência a recursos de dados ou termos de glossário que não existem no Knowledge Catalog.

Para resolver esse problema, escolha uma destas opções:

• Para prosseguir com uma importação parcial, digite y no prompt. O utilitário importa todos os links de entrada válidos e ignora apenas os links que fazem referência aos recursos ausentes.

• Para cancelar e corrigir os recursos ausentes, digite n para cancelar a execução. Verifique se os IDs de entrada no documento de origem correspondem exatamente aos nomes dos recursos no Catálogo de Conhecimento. Corrija os recursos ausentes ou erros de digitação e execute o script de importação novamente.

Resolver falhas no job de importação do Knowledge Catalog

Se um job de importação for interrompido ou falhar no meio da execução, não será necessário reiniciar todo o processo ou modificar o arquivo de origem do Google Planilhas.

O utilitário rastreia os lotes importados usando uma pasta de arquivo no bucket de preparo do Cloud Storage.

Para retomar o job, siga estas etapas:

1. Execute o utilitário de importação novamente. O utilitário detecta o estado da execução anterior e exibe o seguinte prompt:

   Found X existing file(s) in archive folder from a previous incomplete import
   Continue using existing files? [y/N]:
   

2. Digite y. O utilitário ignora os lotes que já foram importados e processa apenas os arquivos restantes.

Tempo limite de script ou erros de SSL durante a execução

Ao executar o script do utilitário de importação ou exportação, a execução é interrompida, atinge o tempo limite ou retorna erros de SSL no terminal.

Esse problema ocorre devido aos seguintes erros no nível da rede:

• Intercepção de proxy corporativo ou firewall: um proxy de segurança ou firewall está interceptando e inspecionando o tráfego HTTPS, o que invalida os certificados SSL.
• Restrições de VPN ativas: sua configuração de VPN restringe o tráfego de saída para determinadas APIs do Google Cloud ou endpoints do Google Planilhas.
• Instabilidade na rede local: uma queda temporária na conectividade com a Internet interrompeu a sessão.

Para resolver esses problemas de rede, siga estas etapas:

• Confira se você tem uma conexão de rede estável.

• Inspecionar as configurações de proxy e firewall

• Verifique a configuração da VPN.

• Confie nas novas tentativas integradas: o script utilitário tem uma lógica de nova tentativa integrada para falhas temporárias de rede. Se a queda de rede for momentânea, aguarde o script concluir as tentativas antes de reiniciar a execução.

Erro de URL de planilha inválido

Quando você tenta executar um utilitário de importação ou exportação, a interface de linha de comando retorna um erro Invalid spreadsheet URL e interrompe a execução.

Esse problema ocorre quando o script não consegue analisar o link da planilha do Google fornecido ou não tem autorização para visualizar o arquivo. Estas são as causas mais comuns:

• URL inválido: o URL não corresponde ao formato de caminho padrão do Google Planilhas.
• ID da planilha ausente: o caminho não tem o ID alfanumérico exclusivo que aponta para sua planilha específica.
• Restrições de acesso: sua conta de serviço autenticada não tem permissão para visualizar ou editar a planilha, o que impede o utilitário de validar o link.

Para resolver esse problema, verifique o link da planilha e as configurações de acesso:

• Valide o prefixo do URL: verifique se o URL da planilha que você transmite ao utilitário começa com o seguinte caminho padrão do Google Planilhas: https://docs.google.com/spreadsheets/

• Verifique o ID da planilha: confirme se o URL inclui o ID exclusivo da sua planilha. Um URL válido precisa seguir esta estrutura: https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit

• Verifique as permissões de acesso: abra o arquivo do Google Planilhas em um navegador, clique em Compartilhar e confirme se você adicionou o e-mail da sua conta de serviço como Editor.

Resolver erros de URL de glossário inválido

Quando você tenta executar um utilitário de importação ou exportação para glossários, a interface de linha de comando retorna um erro Invalid glossary URL e interrompe a execução. Verifique se não há um URL de glossário inválido nos parâmetros.

Esse problema ocorre se o script não conseguir analisar o caminho do recurso do glossário do Knowledge Catalog fornecido ou não tiver autorização para visualizar o recurso. Estas são as causas mais comuns:

• Caminho de recurso inválido: o caminho do recurso não corresponde ao formato padrão do caminho do glossário do Knowledge Catalog.
• ID incorreto: o caminho contém um ID do projeto, local de região ou ID de glossário incorreto.
• Restrições de acesso ou recurso ausente: o glossário não existe ou sua conta de serviço autenticada não tem as permissões do IAM necessárias para acessá-lo.

Para resolver esse problema, verifique o caminho do recurso do glossário e as credenciais:

• Valide a estrutura do caminho do recurso: verifique se o caminho do glossário que você transmite ao utilitário corresponde ao seguinte formato padrão do Knowledge Catalog: projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID

• Verifique os identificadores no caminho: use o ID do projeto, o local e o ID do glossário corretos.

• Confirme a existência e o acesso ao recurso: confirme se o glossário existe com o ID especificado e se a conta de serviço autenticada recebeu os papéis necessários do IAM.

Abra os registros de execução

Os utilitários de importação e exportação geram registros de execução detalhados durante a execução. Se o job de importação falhar, verifique os registros para encontrar erros específicos. Esses registros ajudam você a auditar o processo de transferência e identificar entradas ignoradas ou avisos de formatação.

• Local do registro: os utilitários de importação e exportação gravam arquivos de registro no diretório logs/ no caminho de execução local.
• Formato do registro: cada arquivo de registro é anexado com um carimbo de data/hora para que você possa localizar registros de uma execução específica.