O Google Cloud fornece as ferramentas para monitorar a confiabilidade dos seus projetos com o Google Cloud Monitoring e depurar problemas com os registros de erros do 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 seus erros:
- Monitore o estado dos seus projetos com métricas de casa inteligente.
- Investigue problemas verificando as descrições detalhadas dos erros nos registros.
Se quiser, teste sua ação compartilhando com outros usuários. Trate erros e exceções de maneira adequada.
Erros de monitoramento
Você pode 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 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 de 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 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.
| 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 o requestId no Cloud Logging do GCP para verificar os registros do serviço de casa
inteligente.
|
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 de erro HTTP 5xx do seu serviço.
Use o requestId no Cloud Logging do GCP 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 disputa. |
GAL_BAD_3P_RESPONSE |
O Google não consegue analisar a resposta do seu serviço de vinculação de contas
devido a um formato ou valores inválidos no payload.
Use o requestId no Logging do GCP para verificar os registros de erros
no seu serviço de vinculação de contas.
|
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 Cloud Logging, entre em contato 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 Cloud Logging, 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 precisa
vincular a conta novamente para continuar usando seu serviço.
Se você notar um aumento na taxa desse erro no Cloud Logging, 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 um aumento na taxa desse erro no Cloud Logging, 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
atualização 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 do serviço de casa inteligente.
|
INVALID_JSON |
A resposta JSON não pode ser analisada ou entendida.
Verifique a estrutura da sua resposta JSON em busca de sintaxe inválida, 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 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 resposta indica um código de erro não reconhecido.
Se a resposta da solicitação indicar um erro, use um dos 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 correspondentes e está estruturado corretamente como um campo JSON. |
PARTNER_RESPONSE_INVALID_STATUS |
A resposta não indica um status ou indica um incorreto.
As respostas às solicitações de fulfillment de intent precisam indicar um status com SUCCESS, OFFLINE, ERROR, EXCEPTIONS. Você
pode encontrar 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 faltando na
resposta.
Verifique se a resposta de execução está estruturada corretamente e se os resultados de todas as intenções da solicitação estão presentes na resposta. |
PARTNER_RESPONSE_MISSING_DEVICE |
Um ou mais dispositivos presentes na solicitação estão faltando 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 uma resposta de execução correta. |
PARTNER_RESPONSE_NOT_OBJECT |
Não é possível analisar a resposta 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 compatíveis. Verifique também se a resposta está estruturada corretamente como um objeto JSON. |
PROTOCOL_ERROR |
Erro ao processar a solicitação.
Use o requestId no Cloud Logging do Google para verificar os registros do serviço de
casa inteligente.
|
RELINK_REQUIRED |
A resposta indicou um erro relinkRequired, que
pede ao usuário para vincular novamente as contas do Google e do parceiro.
Consulte os códigos de erro compatíveis para mais informações. |
RESPONSE_TIMEOUT |
A solicitação atingiu o tempo limite 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 atendimento de intent 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 sendo descartada. Além disso, se não for possível abrir novas conexões com um servidor. |
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" no 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.
Correções de teste
Depois de identificar os erros e aplicar as 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 Test Suite, que explica como testar suas mudanças de maneira eficaz.
Recursos de aprendizagem
Este documento fornece as etapas para resolver erros 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.