O Google Cloud oferece ferramentas para monitorar a confiabilidade dos seus projetos com Google Cloud Monitoring e depurar problemas com 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.
Se quiser, você pode testar sua ação compartilhando com outros usuários. Gerencie erros e exceções de maneira adequada.
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 do serviç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 projeto.
- O gráfico de latência do 95º percentil é um indicador importante de como a integração do Cloud-to-cloud está funcionando para seus 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 detectar comportamentos inesperados.
- 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 do 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 | Para colocar em prática |
|---|---|---|
ACTION_NOT_AVAILABLE |
O comando é inválido para o estado atual do dispositivo (por exemplo, "Definir temperatura" enquanto o dispositivo está desligado).
Verifique os traços do dispositivo e a lógica de estado atual no seu atendimento. |
Sim |
AGENT_ISSUE |
Ocorreu um problema geral com o agente de nuvem do parceiro.
Verifique se há exceções ou falhas não processadas nos registros de atendimento. |
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 |
APP_LAUNCH_FAILED |
Não foi possível iniciar o app de terceiros no dispositivo de destino.
Verifique o appId e se o app é compatível com o hardware de destino. |
Sim |
AUTH_EXPIRED |
O token de acesso do OAuth expirou e não pode ser atualizado.
Verifique a rotação do token de atualização e confira se o usuário não revogou o acesso. |
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 do 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.
|
|
CHANNEL_SWITCH_FAILED |
O dispositivo não conseguiu mudar para o canal de mídia solicitado.
Verifique os nomes/números dos canais e o status da assinatura do usuário. |
Sim |
CHARGER_ISSUE |
O dispositivo informa um problema de hardware com o sistema de carregamento.
O parceiro precisa investigar a telemetria no nível do hardware e a integridade da bateria. |
Sim |
CHECK_PARTNER_APP |
O erro exige que o usuário abra o app do parceiro para ser resolvido.
Use esse código para erros que exigem interação complexa da interface (por exemplo, atualizações de firmware). |
Sim |
COMMAND_FAILED |
Ocorreu uma falha genérica durante a execução de um comando.
Verifique os registros de atendimento para encontrar o requestId
específico e descobrir a causa principal.
|
Sim |
COMMAND_INSERT_FAILED |
O Google não conseguiu enfileirar ou processar o comando para o dispositivo.
Investigue o desempenho de gravação do banco de dados ou a lógica interna de enfileiramento de comandos. |
Sim |
DEVICE_NOT_FOUND |
O ID do dispositivo na solicitação não existe no lado do parceiro.
Verifique se a nuvem aciona um requestSync quando um usuário
adiciona ou exclui dispositivos.
|
Sim |
ERROR_STATUS |
A resposta indicou um status "ERROR" não específico sem um código.
Sempre inclua uma string errorCode específica para melhorar
os dados do painel e da TTS do usuário.
|
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 atendimento foi bloqueado por robots.txt ou filtros de segurança.
Verifique se o endpoint de atendimento 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 atendimento.
Investigue falhas, tempos limite ou erros 502/503 do gateway 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_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). |
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 |
FAULTY_BATTERY |
O hardware do dispositivo informa que a bateria está com falha ou descarregada.
Instrua o usuário a substituir a bateria física usando TTS ou o app. |
Sim |
FUNCTION_NOT_SUPPORTED |
O modo ou a função solicitada não é compatível com o dispositivo.
Confira se a resposta SYNC reflete com precisão os recursos do
dispositivo.
|
Sim |
HARD_ERROR |
Uma falha não temporária que não será resolvida sem intervenção manual.
Use isso para falhas permanentes de hardware ou estados de conta irrecuperáveis. |
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 Cloud Logging do Google Cloud 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 |
LOCK_FAILURE |
Não foi possível mover a fechadura inteligente para o estado solicitado.
Investigue falhas físicas, falta de energia ou falhas no motor do hardware da fechadura. |
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 |
MISSING_STATE |
A resposta QUERY não continha o estado do dispositivo solicitado.
Verifique se todas as características definidas em SYNC estão incluídas em
todas as respostas de QUERY.
|
Sim |
NETWORK_PROFILE_NOT_RECOGNIZED |
O perfil de rede solicitado é desconhecido para o dispositivo.
Verifique se a string do nome do perfil corresponde aos perfis compatíveis na resposta SYNC.
|
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 |
OAUTH_RECONNECT_CALL_TO_ACTION |
Aciona uma notificação para que o usuário vincule novamente a conta.
Use isso quando a sessão de um usuário for invalidada e exigir uma nova autenticação manual do OAuth. |
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 atendimento. |
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.
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. |
Sim |
PROTOCOL_ERROR |
Ocorreu um erro no protocolo de comunicação subjacente.
Investigue problemas de cabeçalho HTTP ou falhas no handshake de TLS. |
Sim |
RELINK_REQUIRED |
O usuário precisa vincular a conta novamente para continuar usando a integração.
Verifique se o servidor retorna esse código quando um token de atualização é permanentemente inválido. |
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 atendimento 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 |
SCENE_CANNOT_BE_APPLIED |
Não foi possível ativar a cena solicitada (por exemplo, dispositivos ausentes).
Verifique a integridade interna das cenas do usuário na nuvem do parceiro. |
Sim |
STREAM_UNPLAYABLE |
Não foi possível iniciar ou houve uma falha no stream da câmera.
Verifique a sinalização WebRTC/HLS e confira se o URL do stream é válido. |
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 |
TRANSIENT_ERROR |
Um erro temporário é um erro que será resolvido sozinho.
Normalmente, esses erros se manifestam como uma conexão com um dispositivo ou serviço sendo descartada. Além disso, se não for possível abrir novas conexões com um servidor. |
|
UNABLE_TO_LOCATE_DEVICE |
Não foi possível encontrar o dispositivo usando a característica Locator (por exemplo,
o ping falhou).
Verifique a conectividade local do dispositivo (Wi-Fi/Bluetooth). |
Sim |
UNABLE_TO_RING_DEVICE |
O dispositivo foi alcançado, mas não foi possível acionar a função de toque/alerta.
Verifique o estado do alerta/alto-falante e os níveis de volume do hardware. |
Sim |
UNABLE_TO_SILENCE_DEVICE |
Não foi possível interromper o alerta/toque ativo do dispositivo.
Investigue falhas de comunicação entre a nuvem e o dispositivo físico. |
Sim |
UNEXPECTED_ERROR_CHECK_DEVICE_APP |
Ocorreu um erro inesperado. O usuário precisa verificar o app do parceiro.
Use como um recurso de tratamento geral para erros sem um equivalente específico compatível com o Google. |
Sim |
UNKNOWN_ERROR |
Uma falha genérica sem mais detalhes.
Procure substituir isso por códigos de erro mais específicos para melhorar a solução de problemas. |
Sim |
UNLOCK_FAILURE |
A fechadura inteligente não conseguiu alcançar o estado "Destrancada".
Investigue problemas de hardware, bateria fraca ou entradas de PIN inválidas. |
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. É necessário escrever consultas para filtrar os registros e encontrar os que você 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. Oferecemos 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 problemas 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.