Google Cloud oferece as ferramentas para monitorar a confiabilidade dos projetos com Google Cloud Monitoring e depurar problemas com os registros de erro Google Cloud Logging. Sempre que acontece 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 solucionar os erros:
- Monitore o estado dos seus projetos com métricas de casa inteligente.
- Investigue problemas verificando as descrições detalhadas de erro nos registros de erros.
Erros de monitoramento
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 a depuração:
- O gráfico Taxa de sucesso é o primeiro gráfico que começa quando você está monitorando a confiabilidade dos projetos. As quedas neste gráfico podem indicar uma interrupção para uma parte ou toda a base de usuários. Recomendamos que você monitore atentamente este gráfico para ver se há irregularidades no projeto após cada alteração ou atualização.
- O gráfico de latência no percentil 95 é um indicador importante do desempenho da ação de casa inteligente para os usuários. Flutuações repentinas nesse gráfico podem indicar que seus sistemas podem não conseguir acompanhar as solicitações. Recomendamos verificar esse gráfico periodicamente para identificar qualquer comportamento inesperado.
- Os gráficos de Detalhamento de erros são mais úteis quando se trata de solução de problemas nas suas integrações. Para cada erro destacado no gráfico de porcentagem de sucesso, um código de erro é exibido no detalhamento. Confira os erros sinalizados pelo Google Home platform e como resolvê-los na tabela abaixo.
Códigos de erro da plataforma
Veja alguns códigos de erro comuns que podem ser encontrados 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.
| 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.
Use requestId no GCP Logging para verificar os registros do serviço de casa inteligente.
|
BACKEND_FAILURE_URL_TIMEOUT |
A solicitação do Google expirou ao tentar acessar o serviço.
Verifique se o serviço está on-line, aceita 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 requestId no GCP Logging para verificar os registros do serviço de casa inteligente.
|
DEVICE_NOT_FOUND |
O dispositivo não existe no lado do serviço do parceiro.
Isso normalmente indica uma falha na sincronização de dados ou uma disputa. |
GAL_BAD_3P_RESPONSE |
O Google não pode analisar a resposta do serviço de vinculação de conta
devido a formato ou valores inválidos no payload.
Use o requestId no GCP Logging para verificar os registros de erro
no serviço de vinculação de contas.
|
GAL_INTERNAL |
Ocorreu um erro interno quando o Google tentou recuperar um token de acesso.
Se você vir uma taxa maior desse erro no Logging no GCP, entre em contato para mais informações. |
GAL_INVALID_ARGUMENT |
Ocorreu um erro interno quando o Google tentou recuperar um token de acesso.
Se você vir uma taxa maior desse erro no Logging no GCP, entre em contato 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 mais ser atualizados. O usuário precisará
vincular a conta novamente para continuar usando o serviço.
Se você vir uma taxa maior desse erro no Logging no GCP, entre em contato para mais informações. |
GAL_PERMISSION_DENIED |
Ocorreu um erro interno do Google quando o compartilhamento de tokens não está autorizado.
Se você vir uma taxa maior desse erro no Logging no GCP, entre em contato para mais informações. |
GAL_REFRESH_IN_PROGRESS |
O token de acesso do usuário expirou e já existe outra tentativa simultânea de atualização em andamento.
Isso não é um problema, e nenhuma ação é necessária. |
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 foi invalidado pelo serviço. Use o requestId no GCP Logging para verificar os registros do serviço de casa inteligente.
|
INVALID_JSON |
Não é possível analisar ou compreender a resposta JSON.
Verifique se há sintaxes inválidas na estrutura da resposta JSON, como colchetes não correspondentes, vírgulas ausentes e 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 uma taxa maior desse código, verifique se também é possível perceber uma taxa maior de erros relacionados a intents de casa inteligente ou solicitações de token de atualização. |
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 código fornecido pelos nossos códigos de erro compatíveis. |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Não é possível analisar o campo payload da resposta como um objeto JSON.
Verifique se o campo de payload na resposta da solicitação tem colchetes 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 da intent precisam indicar um status com SUCCESS, OFFLINE, ERROR, EXCEPTIONS. Veja 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.
Verifique 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 mais sobre como criar corretamente uma resposta de execução. |
PARTNER_RESPONSE_NOT_OBJECT |
Não é possível analisar a resposta como um objeto JSON.
Verifique em todos os campos da resposta da solicitação se há caracteres indesejados, colchetes de correspondência ou erros de formatação. Alguns caracteres Unicode podem não ser compatíveis. Além disso, verifique se a resposta está estruturada corretamente como um objeto JSON. |
PROTOCOL_ERROR |
Falha ao processar a solicitação.
Use 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 período de tempo limite para enviar uma resposta é de nove 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 fulfillment de intents precisam ser estruturadas de acordo com os documentos de casa inteligente e indicar o status. |
TRANSIENT_ERROR |
Um erro temporário é um erro que se resolve sozinho.
Normalmente, esses erros se manifestam como uma conexão a um dispositivo ou serviço que está sendo descartado. Também se não for possível abrir novas conexões com um servidor. |
Logs de pesquisa
Depois de se familiarizar com o monitoramento das integrações usando métricas, a próxima etapa é solucionar erros específicos usando Cloud Logging. Um registro de erros é 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 em Google Cloud que sempre enviam registros para seu projeto. É necessário escrever consultas para filtrar seus registros e encontrar as que você precisa. As consultas podem ser baseadas em um intervalo de tempo, recurso, 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 do 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 registros do projeto.
Use o botão Gravidade para filtrar por Emergência, Informações, Depurar e outros níveis de registro de gravidade.
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 string, 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 consulta eficaz de registros.
Correções de teste
Depois de identificar os erros e aplicar as atualizações para corrigi-los, recomendamos testar as correções completamente com o 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 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: Depuração de casa inteligente: guia de início rápido para depurar a integração de casa inteligente com a nuvem.
- Codelab Depuração de casa local: guia de início rápido para depurar a integração local de casa inteligente.