Este documento descreve como resolver problemas e erros comuns que podem ocorrer ao encontrar ao importar e exportar glossários e links de entrada no Knowledge Catalog (antigo Dataplex Universal Catalog).
Se você precisar de ajuda para resolver um problema que não é abordado nesta página, entre em contato com o suporte do Google Cloud.
Links de entrada ausentes na planilha do Google exportada
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 da planilha do Google gerada.
Esse problema ocorre se o utilitário de exportação ignorar 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 a entrada de destino associada ao link.
Tipo de link de entrada inválido: o link de entrada usa um tipo de relacionamento não aceito ou não reconhecido. Os tipos válidos são limitados a
definition,relatedesynonym.Referências de entrada incompletas: os metadados de entrada não têm os campos de esquema necessários, fazendo com que a verificação de validação ignore o recurso.
Para resolver esse problema, faça as seguintes verificações:
Verificar permissões: confirme se o principal que executa o script recebeu os papéis necessários.
Inspecionar registros de execução: verifique o terminal ou os registros de script em busca de avisos que contenham
Skipping redacted entrylink. Os registros geram os IDs de recursos específicos dos links de entrada ignorados e o motivo da omissão.Verificar a validade do esquema de links: se você modificou esses links de forma programática, verifique se as propriedades deles correspondem aos requisitos do esquema.
Nenhum termo encontrado no erro do glossário
Ao
exportar glossários para uma planilha do Google,
a execução falha ou retorna um resultado vazio com a mensagem
No terms found in the glossary, mesmo que o glossário comercial contenha
termos ativos.
Esse problema ocorre se o script não conseguir localizar o glossário especificado ou não tiver as permissões de acesso necessárias para recuperar o conteúdo. 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 a configuração e as permissões:
Verifique o ID do glossário: no Google Cloud console, acesse a página Glossários do Knowledge Catalog, selecione o glossário e confirme se o ID do recurso corresponde ao ID que você está transmitindo ao 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 representada) receberam os papéis necessários.
Valide a estrutura do URL do glossário: se você estiver transmitindo um caminho ou URL de recurso direto para o script, verifique se ele segue o formato correto do recurso 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 links de entrada, o script pausa e mostra um aviso semelhante a este:
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 a planilha do Google contiver links de entrada que referenciam recursos de dados ou termos de glossário que não existem no Knowledge Catalog.
Para resolver esse problema, escolha uma das seguintes opções:
Para continuar com uma importação parcial, digite
yno prompt. O utilitário importa todos os links de entrada válidos e ignora apenas os links que referenciam os recursos ausentes.Para cancelar e corrigir os recursos ausentes, digite
npara cancelar a execução. Verifique se os IDs de entrada no documento de origem correspondem exatamente aos nomes de recursos no Knowledge Catalog. Corrija os recursos ausentes ou erros tipográficos e execute o script de importação novamente.
O job de importação falha ou é interrompido no meio
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 a planilha do Google de origem.
O utilitário acompanha os lotes importados com sucesso usando uma pasta de arquivo no bucket de preparo do Cloud Storage.
Para retomar o job, siga estas etapas:
Execute o utilitário de importação novamente. O utilitário detecta o estado da execução anterior e mostra o seguinte prompt:
Found X existing file(s) in archive folder from a previous incomplete import Continue using existing files? [y/N]:Digite
y. O utilitário ignora os lotes que já foram importados e processa apenas os arquivos restantes.
Tempos 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 de rede:
- Intercepção de proxy ou firewall corporativo: 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: a configuração de VPN restringe o tráfego de saída a determinadas Google Cloud APIs ou endpoints do Planilhas Google.
- Instabilidade da rede local: uma queda temporária na conectividade com a Internet interrompeu a sessão.
Para resolver esses problemas de rede, siga estas etapas:
Verifique se você tem uma conexão de rede estável.
Inspecione as configurações de proxy e firewall.
Verifique a configuração de VPN.
Confie em novas tentativas integradas: o script do utilitário tem lógica de repetição integrada para falhas de rede temporárias. Se a queda de rede for momentânea, aguarde o script concluir as tentativas de repetição antes de reiniciar a execução.
Erro de URL de planilha inválido
Ao tentar 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 se o script não conseguir analisar o link da planilha do Google fornecido ou não tiver autorização para visualizar o arquivo. Estas são as causas mais comuns:
- URL malformado: o URL não corresponde ao formato de caminho padrão do Planilhas Google.
- ID da planilha ausente: o caminho não tem o ID alfanumérico exclusivo que aponta para a planilha específica.
- Restrições de acesso: a conta de serviço autenticada não tem permissão para visualizar ou editar a planilha, impedindo que o utilitário valide 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 transmitido ao utilitário começa com o seguinte caminho padrão do Planilhas Google:
https://docs.google.com/spreadsheets/Verifique o ID da planilha: confirme se o URL inclui o ID exclusivo da planilha. Um URL válido precisa seguir esta estrutura:
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/editVerifique as permissões de acesso: abra a planilha do Google em um navegador, clique em Compartilhar, e confirme se você adicionou o e-mail da conta de serviço como um Editor.
Erro de URL de glossário inválido
Ao tentar executar um utilitário de importação ou exportação de glossários, a interface de linha de comando retorna um erro Invalid glossary URL e interrompe a execução.
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 malformado: o caminho do recurso não corresponde ao formato de caminho do glossário padrão do Knowledge Catalog.
- ID incorreto: o caminho contém um ID do projeto, local da região ou ID do glossário incorreto.
- Restrições de acesso ou recurso ausente: o glossário não existe ou a 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 transmitido ao utilitário corresponde ao seguinte formato padrão do Knowledge Catalog:
projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_IDVerifique 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 do IAM necessários.
Abrir registros de execução
Os utilitários de importação e exportação geram registros de execução detalhados à medida que são executados. Esses registros ajudam 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.