Google Cloud oferece ferramentas para monitorar a confiabilidade dos seus projetos com Google Cloud Monitoring e depurar problemas com Google Cloud Logging registros de erros. Sempre que ocorre uma falha ao atender às intents 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 problemas:
- Monitore o estado dos seus projetos com métricas de casa inteligente.
- Investigue problemas verificando as descrições detalhadas de erros nos registros de erros.
Opcionalmente, você pode testar sua ação compartilhando-a com outros usuários. Lide com erros e exceções de maneira adequada.
Monitorar erros
Você pode usar 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 a depuração:
- O gráfico de taxa de sucesso é o primeiro a ser usado ao 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 esse gráfico de perto 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 sua Cloud-to-cloud integração está funcionando para seus usuários. Flutuações repentinas nesse gráfico podem indicar que seus sistemas não conseguem 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 resolver problemas nas integrações. Para cada erro destacado no gráfico de porcentagem de sucesso, um código de erro é exibido no detalhamento de erros. Confira os erros sinalizados pela Google Home platform e como resolvê-los 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 pela Google Home platform. Consulte a tabela a seguir para informações sobre a 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 |
A 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á com capacidade excessiva. 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 Google Cloud Logging para verificar
os registros de serviço de casa inteligente. Investigue falhas de servidor, tempos limite,
ou erros de gateway 502/503.
|
|
COMMAND_FAILED |
Ocorreu uma falha genérica durante a execução de um comando.
Verifique os registros de fulfillment para o requestId
e encontre 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 atendimento está 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 de servidor, tempos limite ou erros de gateway 502/503. |
Sim |
EXECUTION_BAILOUT_INVALID_RESPONSE |
A resposta JSON estava tão malformada que o processamento foi interrompido.
Use um validador JSON para garantir que a resposta siga rigorosamente os esquemas de intent. |
Sim |
EXECUTION_GAL_BAD_3P_RESPONSE |
Não foi possível vincular a conta 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 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
limpo.
|
Sim |
EXECUTION_GAL_NOT_FOUND |
Os tokens de acesso e 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.
Verifique se os tokens permanecem válidos e sincronizados, trate as mudanças de status da conta de maneira adequada e peça aos usuários para vincular novamente a conta se os tokens forem confirmados como revogados. |
Sim |
EXECUTION_GAL_READ_ONLY_MODE_FOR_3P |
A integração está em 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 |
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 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 de serviço de casa inteligente.
|
|
INVALID_JSON |
A estrutura de 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á quebrada (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 resposta SYNC 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 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 compatível do Google.
Mapeie seus erros internos para a lista de erros oficial. |
Sim |
PARTNER_RESPONSE_INVALID_PAYLOAD |
O campo payload na resposta não é um objeto JSON
objeto.
Verifique a estrutura raiz da resposta de fulfillment. |
Sim |
PARTNER_RESPONSE_INVALID_STATUS |
O status da resposta não era SUCCESS, ERROR ou OFFLINE.
Verifique se cada resultado do dispositivo na 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 de resposta 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 |
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 do banco de dados ou atraso de 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 tempos limite de serviço internos 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 específicos usando Cloud Logging. Um registro de erros é 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 o projeto o tempo todo. É necessário 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.
Você pode usar 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 registro de gravidade.
Você também pode usar o campo "Consulta" no Logs Explorer
para inserir entradas personalizadas. O mecanismo de consulta usado por esse campo oferece suporte a 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 consultas de registros eficazes.
Testar correções
Depois de identificar erros e aplicar atualizações para corrigi-los, recomendamos testar suas correções com Google Home Test Suite. Fornecemos um guia do usuário sobre como usar Test Suite, que orienta você a testar as mudanças de maneira eficaz.
Recursos de aprendizagem
Este documento fornece as etapas para resolver erros na sua ação de casa inteligente. Você também pode consultar nossos codelabs para saber mais sobre a 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 casa inteligente.