update_date: 06/01/2023
Google Cloud fornece as ferramentas para monitorar a confiabilidade dos projetos com Google Cloud Monitoring e depurar problemas com registros de erro Google Cloud Logging. Sempre que ocorre uma falha ao atender às intents do usuário, o pipeline do Google Home Analytics registra essa falha nas 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 os problemas verificando as descrições detalhadas nos registros de erros.
Como monitorar erros
É possível usar Google Cloud Monitoring dashboards para acessar as métricas do projeto. Alguns gráficos são especialmente úteis para monitorar a qualidade e depurar:
- O gráfico de Taxa de sucesso é o primeiro a começar quando você monitora a confiabilidade dos seus projetos. Quedas nesse gráfico podem indicar uma interrupção do serviço para parte ou toda a base de usuários. Recomendamos monitorar de perto esse gráfico em busca de irregularidades após cada alteração ou atualização no projeto.
- 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 de erro é exibido no detalhamento. Confira os erros sinalizados pelo Google Home platform e como solucioná-los na tabela abaixo.
Códigos de erro da plataforma
Aqui estão 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 do 401 do seu
serviço.
Use o requestId no Logging do GCP para verificar os registros de 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 o requestId no Logging do GCP para verificar os registros de 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 disputa. |
GAL_BAD_3P_RESPONSE |
O Google não pode analisar a resposta do seu serviço de vinculação de contas
devido a formatos ou valores inválidos no payload.
Use o requestId no Logging do GCP para verificar os registros de erros
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ê notar uma taxa maior desse erro no Logging do 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ê notar uma taxa maior desse erro no Logging do GCP, entre em contato para mais informações. |
GAL_NOT_FOUND |
Os tokens de acesso do usuário e de atualização armazenados no Google são
invalidados e não podem mais ser atualizados. O usuário precisa
vincular a conta novamente para continuar usando seu serviço.
Se você notar uma taxa maior desse erro no Logging do GCP, entre em contato para mais informações. |
GAL_PERMISSION_DENIED |
Ocorreu um erro interno do Google quando o compartilhamento de token não foi
autorizado.
Se você notar uma taxa maior desse erro no Logging do GCP, entre em contato para mais informações. |
GAL_REFRESH_IN_PROGRESS |
O token de acesso do usuário expirou, e outra tentativa simultânea de
atualizá-lo já está 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 seu serviço o invalidou. Use o requestId no Logging do GCP para verificar os registros de serviços de casa inteligente.
|
INVALID_JSON |
Não é possível analisar ou entender a resposta JSON.
Verifique se há sintaxe inválida na estrutura da resposta JSON, como colchetes incompatíveis, 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 há um aumento na taxa de erros relacionados a intents de casa inteligente ou a 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 dos nossos códigos de erro compatíveis. |
PARTNER_RESPONSE_INVALID_PAYLOAD |
Não é possível analisar o campo payload de resposta como um objeto
JSON.
Verifique 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 da intent precisam indicar um status com SUCCESS, OFFLINE, ERROR, EXCEPTIONS. Saiba mais 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 todos os intents da solicitação estão presentes. |
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 nela. |
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 |
A resposta não pode ser analisada como um objeto JSON.
Verifique se todos os campos na resposta da solicitação contêm caracteres não intencionais, colchetes incompatíveis ou erros de formatação. Alguns caracteres Unicode podem não ser compatíveis. Verifique também se a resposta está estruturada corretamente como um objeto JSON. |
PROTOCOL_ERROR |
Falha ao processar a solicitação.
Use o requestId no Google Cloud Logging para verificar os
registros de serviços de casa inteligente.
|
RESPONSE_TIMEOUT |
A solicitação expirou enquanto aguardava a resposta.
O 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 a 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 será resolvido sozinho.
Normalmente, esses erros se manifestam como uma conexão com um dispositivo ou serviço que está sendo descartado. Além disso, se não for possível abrir novas conexões com um servidor. |
Logs de pesquisa
Depois de se familiarizar com o monitoramento das suas 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 dentro do Google Cloud que sempre enviam registros para seu projeto. É preciso criar consultas para filtrar os registros e encontrar os necessários. As consultas podem ser baseadas em um intervalo de tempo, recurso, gravidade do 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 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 registros originados no seu projeto.
Use o botão Gravidade para filtrar por Emergência, Informações, Depuração e outros níveis de registro de gravidade.
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 a 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 com eficiência.
Testar correções
Depois de identificar erros e aplicar atualizações para corrigi-los, recomendamos testar suas correções completamente com Google Home Test Suite. Fornecemos um guia do usuário sobre como usar o Test Suite, que ensina a testar as mudanças de maneira eficaz.
Recursos de aprendizagem
Este documento apresenta as etapas para resolver erros na ação de casa inteligente. Também é possível conferir nossos codelabs para saber mais sobre depuração:
- Codelab: depuração da casa inteligente: guia de início rápido para depurar a integração da nuvem de casa inteligente.
- Codelab de depuração da casa local: guia de início rápido para depurar a integração local de casa inteligente.