O Google Cloud oferece as 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 ocorre uma falha 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 erro nos registros do projeto.
Há duas etapas para resolver os erros:
- Monitore o estado dos seus projetos com métricas de casa inteligente.
- Investigue os problemas verificando as descrições detalhadas nos registros de erros.
Se quiser, você pode testar sua Ação compartilhando-a com outros usuários. Trate os erros e as exceções adequadamente.
Como monitorar erros
Use Google Cloud Monitoring dashboards para acessar as métricas do projeto. Há alguns gráficos importantes que são especialmente úteis para monitorar a qualidade e depurar:
- O gráfico Taxa de sucesso é o primeiro a ser usado para monitorar a confiabilidade dos seus projetos. As quedas nesse gráfico podem indicar uma interrupção para uma parte ou toda a base de usuários. Recomendamos monitorar de perto esse gráfico para detectar irregularidades após cada alteração ou atualização no projeto.
- O gráfico Latência do 95º percentil é um indicador importante do desempenho da sua integração do Cloud-to-cloud para os usuários. Flutuações repentinas nesse gráfico podem indicar que seus sistemas não estão conseguindo acompanhar as solicitações. É recomendável verificar esse gráfico periodicamente para identificar comportamentos inesperados.
- Os gráficos de Detalhamento de erros são mais úteis para solucionar problemas nas integrações. Para cada erro destacado no gráfico de porcentagem de sucesso, um código do erro é exibido no detalhamento de erros. Confira os erros sinalizados pela Google Home platform e como resolver problemas na tabela abaixo.
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 ver uma lista completa de códigos do 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 não processadas ou falhas nos registros de fulfillment. |
Sim |
AGENT_UNAVAILABLE_ERROR |
O Google não conseguiu acessar o URL de fulfillment 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 |
COMMAND_FAILED |
Ocorreu uma falha genérica durante a execução de um comando.
Verifique os registros de fulfillment do requestId específico
para encontrar a causa raiz.
|
Sim |
EXECUTION_BACKEND_FAILURE_URL_ERROR |
O Google recebeu um erro HTTP 4xx (exceto 401) do seu
fulfillment.
Verifique se há respostas 403, 404 ou 400 nos registros do servidor da Web. |
Sim |
EXECUTION_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. |
Sim |
EXECUTION_BACKEND_FAILURE_URL_ROBOTED |
O URL de fulfillment está bloqueado pelo robots.txt ou por filtros de segurança.
Verifique se o endpoint de fulfillment está acessível para os 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. Use o requestId no
Google Cloud Logging para verificar os registros do serviço de casa inteligente.
Adicione verificações de integridade e tratamento de novas tentativas.
Investigue falhas no servidor, tempos limite ou erros de gateway 502/503.
|
Sim |
EXECUTION_BAILOUT_INVALID_RESPONSE |
A resposta JSON estava tão incorreta que o processamento foi cancelado.
Use um validador JSON para garantir que sua resposta siga estritamente os esquemas de intent. |
Sim |
EXECUTION_GAL_BAD_3P_RESPONSE |
A vinculação de contas falhou devido a um formato inválido na resposta do token.
Verifique se o formato de resposta do 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 de agentUserId está estável e não
foi limpo.
|
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 forma adequada e exija que os usuários vinculem a conta novamente se for confirmado que os tokens foram revogados. |
|
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 "somente visualização". |
Sim |
EXECUTION_GAL_UNLINKED_BY_3P |
A conta foi desvinculada de forma proativa 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 |
O payload de resposta JSON não pôde ser analisado pelo Google.
Verifique se há erros de sintaxe, colchetes ausentes ou caracteres inválidos na resposta. |
Sim |
INVALID_AUTH_TOKEN |
O Google recebeu um código do erro HTTP 401 do seu serviço.
O token de acesso não expirou, mas foi invalidado pelo serviço. 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 as respostas. |
Sim |
NOT_IMPLEMENTED |
A intent ou o atributo solicitado não foi implementado pelo parceiro.
Inclua na resposta SYNC apenas os atributos que você
implementou totalmente.
|
Sim |
OPEN_AUTH_FAILURE |
O token de acesso do usuário expirou e o Google não consegue atualizá-lo
ou o Google recebeu um código do 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 compatibilidade do 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 todos os resultados de dispositivos na resposta incluem 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 de resposta com base na documentação para desenvolvedores 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 |
O campo obrigatório payload está ausente na resposta.
Verifique se o objeto JSON de nível superior inclui uma chave payload.
|
Sim |
PARTNER_RESPONSE_NOT_OBJECT |
Não foi possível analisar a resposta inteira como um objeto JSON.
Verifique se há caracteres extras ou conteúdo que não seja 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 encontrou o ID de rastreamento 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 atributo) está indisponível.
Verifique se o dispositivo está "Ocupado" ou se foi desativado temporariamente. |
Sim |
RESPONSE_TIMEOUT |
O serviço de fulfillment não respondeu em até 9 segundos.
Otimize a latência de 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 para ver se há tempos limite de serviço interno entre os hubs de nuvem e de dispositivo. |
Sim |
Logs de pesquisa
Depois de se familiarizar com o monitoramento das integrações usando métricas, a próxima etapa é resolver erros específicos usando o Cloud Logging. Um registro de erro é uma entrada semelhante a JSON com campos que contêm informações úteis, como horário, código de erro e detalhes sobre a intent de casa inteligente de origem.
Há vários sistemas no Google Cloud que enviam registros para seu projeto o tempo todo. É preciso escrever consultas para filtrar os registros e encontrar os que você precisa. As consultas podem ser baseadas em um Período, Recurso, Gravidade do 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 que se originam do seu projeto.
Use o botão Gravidade para filtrar por Emergência, Informações, Depuração e outros níveis de gravidade de registro.
Também é possível usar o campo "Consulta" no 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 de consultas, 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.
Como testar correções
Depois de identificar os erros e aplicar as atualizações para corrigi-los, recomendamos testar as correções minuciosamente com o Google Home Test Suite. Oferecemos um guia do usuário sobre como usar o Test Suite, que orienta você sobre como testar suas mudanças de maneira eficaz.
Recursos de aprendizagem
Este documento mostra as etapas para resolver problemas na sua ação de casa inteligente. Você também pode conferir 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 casa inteligente com a nuvem.
- Codelab de depuração de casa local: guia de início rápido para depurar a integração local de casa inteligente.