O Google Cloud oferece ferramentas para monitorar a confiabilidade dos seus projetos com Google Cloud Monitoring e depurar problemas com registros de erros 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 conferindo as descrições detalhadas nos registros de erros.
Você também pode testar sua Ação compartilhando-a com outros usuários. Processe erros e exceções corretamente.
Monitorar erros
É possível 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 depurar:
- O gráfico Taxa de sucesso é o primeiro a ser usado quando você está monitorando a confiabilidade dos seus projetos. Quedas nesse gráfico podem indicar uma interrupção para parte ou toda a base de usuários. Recomendamos monitorar atentamente o gráfico para detectar irregularidades após cada mudança ou atualização no projeto.
- O gráfico Latência do percentil 95 é um indicador importante de como a integração do Cloud-to-cloud está funcionando para os usuários. Flutuações repentinas nesse gráfico podem indicar que seus sistemas não estão capazes de acompanhar as solicitações. É recomendável verificar esse gráfico periodicamente para detectar comportamentos inesperados.
- Os gráficos Error Breakdown são mais úteis para solucionar 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 pelo Google Home platform e como resolvê-los na tabela abaixo.
Códigos de erro 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 mais informações sobre solução de problemas.
| Código do erro | Descrição |
|---|---|
BACKEND_FAILURE_URL_ERROR |
O Google recebeu um código de erro HTTP 4xx diferente de 401 do seu serviço.
Usar o requestId no GCP Logging para verificar os registros do serviço de casa inteligente.
|
BACKEND_FAILURE_URL_TIMEOUT |
O tempo limite da solicitação do Google foi atingido ao tentar acessar seu serviço.
Verifique se o serviço está on-line, aceitando conexões e não está com capacidade máxima. Além disso, verifique se o dispositivo de destino está ligado, conectado e sincronizado. |
BACKEND_FAILURE_URL_UNREACHABLE |
O Google recebeu um código de erro HTTP 5xx do seu serviço.
Usar o requestId no GCP Logging para verificar os registros do serviço de casa inteligente.
|
DEVICE_NOT_FOUND |
O dispositivo não existe no serviço do parceiro.
Isso normalmente indica uma falha na sincronização de dados ou uma condição de corrida. |
GAL_BAD_3P_RESPONSE |
O Google não consegue analisar a resposta do serviço de vinculação de conta
devido a um formato ou valores inválidos no payload.
Utilize o requestId no GCP Logging para verificar os registros de erro no serviço de vinculação de conta.
|
GAL_INTERNAL |
Ocorreu um erro interno do Google ao tentar recuperar um token de acesso.
Se você notar um aumento na taxa desse erro no registro do GCP, entre em contato com a gente para mais informações. |
GAL_INVALID_ARGUMENT |
Ocorreu um erro interno do Google ao tentar recuperar um token de acesso.
Se você notar um aumento na taxa desse erro no registro do GCP, entre em contato com a gente para mais informações. |
GAL_NOT_FOUND |
Os tokens de acesso e de atualização do usuário armazenados no Google são
invalidados e não podem ser atualizados. O usuário precisa
vincular novamente a conta para continuar usando seu serviço.
Se você notar um aumento na taxa desse erro no registro do GCP, entre em contato com a gente para mais informações. |
GAL_PERMISSION_DENIED |
Ocorreu um erro interno do Google quando o compartilhamento de tokens não foi
autorizado.
Se você notar um aumento na taxa desse erro no registro do GCP, entre em contato com a gente para mais informações. |
GAL_REFRESH_IN_PROGRESS |
O token de acesso do usuário expirou, e outra tentativa simultânea de
refrescá-lo já está em andamento.
Isso não é um problema e não é necessário fazer nada. |
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 GCP Logging para verificar os registros do serviço de casa inteligente.
|
INVALID_JSON |
A resposta JSON não pode ser analisada ou compreendida.
Verifique se a estrutura da resposta JSON tem sintaxe inválida, como colchetes incompatíveis, vírgulas ausentes, caracteres inválidos. |
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 atualização de token. |
PARTNER_RESPONSE_INVALID_ERROR_CODE |
A resposta indica um código de erro não reconhecido.
Se a resposta da solicitação indicar um erro, use um fornecido pelos nossos códigos de erro compatíveis. |
PARTNER_RESPONSE_INVALID_PAYLOAD |
O campo payload da resposta não pode ser analisado como um objeto JSON.
Confira se o campo de payload na resposta da solicitação tem colchetes correspondentes e está estruturado corretamente como um campo JSON. |
PARTNER_RESPONSE_INVALID_STATUS |
A resposta não indica um status ou indica um status incorreto.
As respostas às solicitações de fulfillment de intent precisam indicar um status com SUCCESS, OFFLINE, ERROR, EXCEPTIONS.
Confira mais informações sobre
como lidar com erros e exceções.
|
PARTNER_RESPONSE_MISSING_COMMANDS_AND_DEVICES |
Uma ou mais intents presentes na solicitação estão ausentes na
resposta.
Verifique se a resposta de execução está estruturada corretamente e se os resultados de todas as intents da solicitação estão presentes na resposta. |
PARTNER_RESPONSE_MISSING_DEVICE |
Um ou mais dispositivos presentes na solicitação estão ausentes na
resposta.
Confirme se a resposta de execução está estruturada corretamente e se todos os IDs de dispositivo da solicitação estão presentes na resposta. |
PARTNER_RESPONSE_MISSING_PAYLOAD |
A resposta não contém um campo payload.
Inclua um campo de payload na resposta da solicitação. Saiba como criar corretamente uma resposta de execução. |
PARTNER_RESPONSE_NOT_OBJECT |
A resposta não pode ser analisada como um objeto JSON.
Verifique todos os campos na resposta da solicitação para encontrar caracteres indesejados, colchetes incompatíveis ou erros de formatação. Alguns caracteres Unicode podem não ser aceitos. Além disso, verifique se a resposta está corretamente estruturada como um objeto JSON. |
PROTOCOL_ERROR |
Erro ao processar a solicitação.
Usar o requestId no Google Cloud Logging para verificar os registros do serviço de casa inteligente.
|
RESPONSE_TIMEOUT |
A solicitação expirou enquanto aguardava a resposta.
O tempo limite para enviar uma resposta é de 9 segundos a partir do momento em que a solicitação é enviada. Envie uma resposta dentro desse período. |
RESPONSE_UNAVAILABLE |
Nenhuma resposta é recebida ou a resposta não indica o status.
As respostas às solicitações de atendimento de intent precisam ser estruturadas conforme os documentos da casa inteligente e indicar o status. |
TRANSIENT_ERROR |
Um erro temporário é um erro que se resolve sozinho.
Normalmente, esses erros aparecem como uma conexão com um dispositivo ou serviço sendo perdida. Além disso, se novas conexões com um servidor não puderem ser abertas. |
Logs de pesquisa
Depois de se sentir confortável monitorando suas integrações usando métricas, a próxima etapa é resolver erros específicos usando o 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 no Google Cloud que enviam registros para seu projeto o tempo todo. Você precisa escrever consultas para filtrar seus registros e encontrar os que você precisa. As consultas podem ser baseadas em um Intervalo de tempo, Recurso, Gravidade de registro ou entradas personalizadas.
Você pode usar os botões de consulta para criar filtros personalizados.
Para especificar um Intervalo de tempo, clique no botão de seleção de intervalo de tempo e escolha uma das opções disponíveis. 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 Severity para filtrar por Emergency, Info, Debug e outros níveis de registro de gravidade.
Também é possível usar o campo de 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 string, 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 consultas de registros eficazes.
Correções de teste
Depois de identificar erros e aplicar atualizações para corrigi-los, recomendamos testar as correções com Google Home Test Suite. Oferecemos um guia do usuário sobre como usar Test Suite, que orienta você a testar suas mudanças de maneira eficaz.
Recursos de aprendizagem
Este documento apresenta as etapas para resolver erros 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 da 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.