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

Este guia ajuda a resolver problemas do Knowledge Catalog ao importar e exportar glossários e links de entrada, incluindo links de entrada ausentes, erros de URL de glossário inválido ou quando um job de importação falha.

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.

Corrigir links de entrada ausentes no Knowledge Catalog

Depois de exportar links de entrada do Knowledge Catalog para uma Planilha Google executando o utilitário de link de entrada de exportação, você percebe que alguns links de entrada (associações) estão ausentes da Planilha 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, related e synonym.

  • 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: verifique se você tem permissões para visualizar os links de entrada ausentes. 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 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 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 digitação.
  • 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 link 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 Google contém 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 y no 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 n para 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.

Resolver problemas de falhas de jobs 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 a Planilha 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:

  1. 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]:

  2. 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 das 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 uma 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 Google fornecida 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 das 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 das 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/edit

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

Resolver erros de URL de glossário inválido

Ao tentar 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 malformado: o caminho de recurso não corresponde ao formato de caminho de glossário padrão do Knowledge Catalog.
  • ID incorreto: o caminho contém um ID do projeto, local da região ou ID de 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_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 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. Se o job de importação falhar, verifique os registros em busca de erros específicos. 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.