refresh_date: 2023-01-06
O Google Cloud fornece ferramentas para monitorar a confiabilidade dos seus projetos com o Google Cloud Monitoring e depurar problemas com os registros de erros do Google Cloud Logging. Sempre que uma falha ocorre ao atender às intenções do usuário, o pipeline do Google Home Analytics registra essa falha nas suas métricas e publica um registro de erros nos registros do projeto.
Há duas etapas para resolver seus erros:
- Monitore o estado dos seus projetos com métricas de casa inteligente.
- Investigue problemas verificando as descrições detalhadas de erros nos registros.
Erros de monitoramento
É possível usar Google Cloud Monitoring dashboards para acessar as métricas do projeto. Há alguns gráficos principais que são especialmente úteis para monitorar a qualidade e depurar:
- O gráfico Taxa de sucesso é o primeiro que você deve usar ao monitorar a confiabilidade dos seus projetos. As quedas neste gráfico podem indicar uma interrupção para uma parte ou toda a sua base de usuários. Recomendamos monitorar de perto esse gráfico para detectar irregularidades após cada mudança ou atualização no seu projeto.
- Os gráficos de Detalhamento de erros são mais úteis para solucionar problemas nas suas integrações. Para cada erro destacado no gráfico de porcentagem de sucesso, um código de erro é mostrado no detalhamento de erros. Confira na tabela abaixo os erros sinalizados pelo Google Home platform e como resolver esses problemas.
Códigos de erro comuns da plataforma
Confira alguns códigos de erro comuns que podem aparecer nos registros do projeto para identificar problemas detectados pelo Google Home platform. Consulte a tabela a seguir para informações sobre solução de problemas. Para conferir uma lista completa de códigos de erro, consulte Erros e exceções.
| Código do erro | Descrição | Ação do parceiro |
|---|---|---|
AGENT_ISSUE |
Ocorreu um problema geral com o agente de nuvem do parceiro.
Verifique se há exceções ou falhas não tratadas nos registros de fulfillment. |
Sim |
AGENT_UNAVAILABLE_ERROR |
O Google não conseguiu acessar o URL de atendimento do parceiro.
Verifique se o servidor está on-line, se o firewall não está bloqueando o Google e se o URL está correto. |
Sim |
BACKEND_FAILURE_URL_TIMEOUT |
O tempo limite da solicitação do Google expirou ao tentar acessar seu serviço.
Verifique se o serviço está on-line, aceitando conexões e não está acima da capacidade. Além disso, verifique se o dispositivo de destino está ligado, on-line e sincronizado. |
|
BACKEND_FAILURE_URL_UNREACHABLE |
O Google recebeu um código de erro HTTP 5xx do seu serviço.
Use o requestId no Cloud Logging do Google Cloud para verificar
os registros do serviço de casa inteligente. Investigue falhas, tempos limite ou erros de gateway 502/503 do servidor.
|
|
COMMAND_FAILED |
Ocorreu uma falha genérica durante a execução de um comando.
Verifique os registros de fulfillment para encontrar o requestId
específico e descobrir a causa raiz.
|
Sim |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
O Google recebeu um erro HTTP 4xx (que não seja 401) do seu
fulfillment.
Verifique os registros do servidor da Web para respostas 403, 404 ou 400. |
Sim |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
O URL de fulfillment foi bloqueado por robots.txt ou filtros de segurança.
Verifique se o endpoint de fulfillment está acessível aos rastreadores/serviços do Google. |
Sim |
EXECUTION_BACKEND_FAILURE_URL_UNREACHABLE |
O Google recebeu um erro HTTP 5xx do seu serviço de fulfillment.
Verifique se o serviço de URL do endpoint está estável, correto e acessível publicamente, e se o serviço está em execução. Adicione verificações de integridade e tratamento de novas tentativas. Investigue falhas, tempos limite ou erros de gateway 502/503 do servidor. |
Sim |
EXECUTION_BAILOUT_INVALID_RESPONSE |
A resposta JSON estava tão malformada que o processamento foi interrompido.
Use um validador JSON para garantir que sua resposta siga estritamente os esquemas de intent. |
Sim |
EXECUTION_GAL_BAD_3P_RESPONSE |
A vinculação da conta falhou devido a um formato inválido na resposta do token.
Verifique se o formato de resposta do seu servidor OAuth corresponde aos requisitos do Google. |
Sim |
EXECUTION_GAL_INSUFFICIENT_CAPABILITIES |
A conta do usuário não tem as permissões necessárias para essa ação.
Verifique os escopos solicitados durante o OAuth e confira se eles correspondem às características necessárias. |
Sim |
EXECUTION_GAL_MAYBE_UNLINKED_BY_3P |
A nuvem do parceiro indica que o usuário desvinculou a conta.
Verifique se o mapeamento agentUserId está estável e não foi
removido.
|
Sim |
EXECUTION_GAL_NOT_FOUND |
Os tokens de acesso e de atualização do usuário armazenados no Google são inválidos ou
não podem ser atualizados, impedindo a autenticação e o acesso ao
serviço do parceiro.
Garanta que os tokens permaneçam válidos e sincronizados, processe as mudanças no status da conta de maneira adequada e exija que os usuários vinculem a conta novamente se os tokens forem confirmados como revogados. |
Sim |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
A integração está no estado somente leitura no lado do parceiro.
Verifique se a conta do usuário está suspensa ou em um modo de manutenção "acesso para assistir". |
Sim |
EXECUTION_GAL_UNLINKED_BY_3P |
A conta foi desvinculada proativamente pelo serviço de terceiros.
Investigue por que o usuário foi desconectado (por exemplo, redefinição de segurança). Verifique se o servidor OAuth do parceiro responde corretamente às solicitações refresh_token do Google para emitir novos tokens de acesso sem problemas.
|
Sim |
EXECUTION_INVALID_JSON |
Não foi possível analisar o payload da resposta JSON pelo Google.
Verifique se há erros de sintaxe, colchetes ausentes ou caracteres inválidos na sua resposta. |
Sim |
INVALID_AUTH_TOKEN |
O Google recebeu um código de erro HTTP 401 do seu serviço.
O token de acesso não expirou, mas seu serviço o invalidou. Use o requestId no Google Cloud Logging para verificar os registros do serviço de casa inteligente.
|
|
INVALID_JSON |
A estrutura da resposta é inválida (por exemplo, campos obrigatórios ausentes).
Valide sua resposta em relação aos esquemas JSON de intent. |
Sim |
MALFORMED_JSON |
A estrutura JSON está corrompida (por exemplo, strings ou objetos não fechados).
Verifique se o fulfillment usa uma biblioteca JSON padrão para serializar respostas. |
Sim |
NOT_IMPLEMENTED |
A intent ou característica solicitada não foi implementada pelo parceiro.
Inclua apenas características na sua resposta SYNC que você
implementou totalmente.
|
Sim |
OPEN_AUTH_FAILURE |
O token de acesso do usuário expirou e o Google não consegue atualizar,
ou o Google recebeu um código de erro HTTP 401 do seu serviço.
Se você notar um aumento na taxa desse código, verifique se também há um aumento na taxa de erros relacionados a intents de casa inteligente ou solicitações de token de atualização. |
|
PARTNER_RESPONSE_INVALID_ERROR_CODE |
A string errorCode retornada não está na lista de idiomas aceitos pelo Google.
Mapeie seus erros internos para a Lista oficial de erros. |
Sim |
PARTNER_RESPONSE_INVALID_PAYLOAD |
O campo payload na resposta não é um objeto JSON válido.
Verifique a estrutura raiz da resposta de fulfillment. |
Sim |
PARTNER_RESPONSE_INVALID_STATUS |
A resposta status não foi SUCCESS, ERROR ou OFFLINE.
Verifique se cada resultado de dispositivo na sua resposta inclui uma string de status válida. |
Sim |
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
A resposta não incluiu resultados para todos os comandos/dispositivos solicitados.
Valide a estrutura da resposta com base na documentação do desenvolvedor do Google Home. Verifique se a resposta não está sendo truncada ou retornando um corpo vazio devido a um erro interno do servidor. Cada item na matriz commands da solicitação precisa ter uma
entrada de resposta correspondente.
|
Sim |
PARTNER_RESPONSE_MISSING_DEVICE |
Um dispositivo específico solicitado pelo Google foi omitido da resposta.
Verifique se a resposta inclui todos os ID fornecidos no
payload da solicitação.
|
Sim |
PARTNER_RESPONSE_MISSING_PAYLOAD |
A resposta não tem o campo obrigatório payload.
Verifique se o objeto JSON de nível superior inclui uma chave payload.
|
Sim |
PARTNER_RESPONSE_NOT_OBJECT |
Não foi possível analisar toda a resposta como um objeto JSON.
Verifique se há caracteres finais ou conteúdo não JSON no corpo da resposta HTTP. Verifique se payload.commands[] é um objeto JSON adequado com IDs, status e estados opcionais.
|
Sim |
REQUEST_ID_NOT_FOUND |
O Google não conseguiu encontrar o ID de acompanhamento interno da solicitação.
Geralmente, é um erro interno da plataforma. Monitore picos e entre em contato com o suporte. |
Sim |
RESOURCE_UNAVAILABLE |
O recurso solicitado (dispositivo ou característica) não está disponível.
Verifique se o dispositivo está "Ocupado" ou foi desativado temporariamente. |
Sim |
RESPONSE_TIMEOUT |
O serviço de fulfillment não respondeu em até 9 segundos.
Otimize a latência do back-end. Verifique se há consultas lentas no banco de dados ou atraso na rede regional. |
Sim |
RESPONSE_UNAVAILABLE |
Nenhuma resposta foi recebida do URL de fulfillment do parceiro.
Verifique se o serviço está em execução e se o endpoint não está falhando. |
Sim |
TIMEOUT |
Ocorreu um tempo limite geral ao processar a intent.
Verifique os registros de tempo limite do serviço interno entre a nuvem e os hubs de dispositivos. |
Sim |
Logs de pesquisa
Depois de se acostumar a monitorar as integrações usando métricas, a próxima etapa é resolver problemas de erros específicos usando Cloud Logging. Um registro de erro é uma entrada semelhante a JSON com campos que contêm informações úteis, como hora, código de erro e detalhes sobre a intent de casa inteligente de origem.
Há vários sistemas em Google Cloud que enviam registros para seu projeto a qualquer momento. Você precisa escrever consultas para filtrar seus registros e encontrar os que precisa. As consultas podem ser baseadas em um período, um recurso, uma gravidade de registro ou entradas personalizadas.
Use os botões de consulta para criar filtros personalizados.
Para especificar um período, clique no botão de seleção de período e escolha uma das opções fornecidas. Isso vai filtrar os registros e mostrar aqueles que se originam no período selecionado.
Para especificar um Recurso, clique no menu suspenso Recurso e escolha Projeto de ação do Google Assistente. Isso adiciona um filtro à consulta para mostrar os registros originados do seu projeto.
Use o botão Gravidade para filtrar por Emergência, Informações, Depuração e outros níveis de gravidade do registro.
Também é possível usar o campo "Consulta" em Logs Explorer para inserir entradas personalizadas. O mecanismo de consulta usado por esse campo é compatível com consultas básicas, como correspondência de strings, e tipos mais avançados, incluindo comparadores (<, >=, !=) e operadores booleanos (AND, OR, NOT).
Por exemplo, a entrada personalizada abaixo retornaria erros originados de um tipo de dispositivo LIGHT:
resource.type = "assistant_action_project" AND severity = ERROR AND jsonPayload.executionLog.executionResults.actionResults.device.deviceType = "LIGHT"
Acesse a Biblioteca de consultas para encontrar mais exemplos de como consultar registros de maneira eficaz.
Testar correções
Depois de identificar os erros e aplicar atualizações para corrigi-los, recomendamos testar as correções completamente com Google Home Test Suite. Fornecemos um guia do usuário sobre como usar o Test Suite, que mostra como testar suas mudanças de maneira eficaz.
Recursos de aprendizagem
Este documento fornece as etapas para resolver erros na sua ação para casa inteligente. Confira também nossos codelabs para saber mais sobre depuração:
- Codelab de depuração de casa inteligente: guia de início rápido para depurar a integração de nuvem de casa inteligente.
- Codelab de depuração do Local Home: guia de início rápido para depurar a integração local de casas inteligentes.