Tratar erros e exceções

Quando dispositivos ou solicitações não funcionam como esperado, é importante fornecer um bom tratamento de erros e comunicação com seus usuários para que eles entendam aconteceu e, sempre que possível, como corrigi-lo. Lembre-se de pensar possíveis cenários de falha e como seu dispositivo responderá: e se um usuário interrompe uma tarefa em andamento? E se um usuário solicitar uma ação em um dispositivo enquanto estiver off-line? Como se planejar para esses problemas e ajudar o usuário a se recuperar podem evitar a frustração do usuário e criar uma experiência de melhor qualidade para seus dispositivos.

Este guia fornece alguns exemplos de respostas de intent que lidam com erros. Consulte a seção Erros e exceções revise os valores válidos de errorCode para erros e exceções.

Exemplo 1: resposta de erro para a intent EXECUTE

Um usuário final tem duas luzes inteligentes instaladas na sala de estar. O usuário emite um comando "acenda as luzes da sala de estar" e o Google enviou um EXECUTE para seu URL de fulfillment. Você descobriu que os dispositivos do usuário estão off-line e não controlável. Portanto, o fulfillment retorna uma resposta EXECUTE com status ERROR e errorCode deviceOffline.

Este exemplo demonstra como retornar uma resposta EXECUTE com uma errorCode de um dispositivo leve, conforme descrito anteriormente:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "light-device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "light-device-id-2"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      }
    ]
  }
}

O Google Assistant vai avisar ao usuário "o dispositivo está não está disponível no momento" após receber a resposta. Lembre-se de que você ainda precisa enviar o estado off-line para dispositivos no estado de relatório após o envio. errorCode deviceOffline na resposta EXECUTE.

Exemplo 2: exceção sem bloqueio para a intent EXECUTE

Um usuário tenta trancar a fechadura inteligente na porta da frente usando um dispositivo com Assistant: É possível controlar a fechadura, mas você achar que a bateria do dispositivo está baixa, então o atendimento do pedido retornará um EXECUTE resposta com status SUCCESS e exceptionCode lowBattery.

Este exemplo demonstra como enviar uma resposta EXECUTE com uma exceptionCode em um dispositivo bloqueado, conforme descrito anteriormente:

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["lock-device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

O Assistant vai enviar um aviso com a mensagem "O dispositivo está baixo bateria" após receber a resposta.

Exemplo 3: notificações proativas de erros

Em alguns casos, pode ser útil alertar os usuários sobre um erro, especialmente para funções que os usuários esperam concluir automaticamente. Para traços que oferecer suporte a notificações proativas, você pode notificar o usuário proativamente enquanto ocorrerá um erro se você tiver implementado smart home notificações proativas.

Uma secadora inteligente está em execução, e alguém abre a porta antes do fim do ciclo. É possível chamar a API Google Home Graph método reportStateAndNotifications para enviar uma notificação proativa com uma errorCode:

Este exemplo demonstra como enviar uma notificação proativa com um errorCode de um dispositivo de secadora, conforme descrito anteriormente:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "dryer-device-id": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      },
      "states": {
        "dryer-device-id": {
          "isRunning": false,
          "isPaused": true
        }
      }
    }
  }
}

O Assistant vai mostrar ao usuário "a porta do dispositivo está abriu" depois de receber a notificação. Você pode enviar o modelo estados de dispositivo e notificações no mesmo payload.

Exemplo 4: notificação de acompanhamento

Para comandos de características compatíveis com notificações de acompanhamento, é possível enviar uma notificação de acompanhamento ao usuário enquanto ocorre um erro ou exceção, se Você implementou smart home notificações de acompanhamento.

Um usuário dá um comando para fechar o portão da garagem, mas a porta está emperrada durante o fechamento. Você pode enviar uma notificação de acompanhamento com um errorCode:

POST https://homegraph.googleapis.com/v1/devices:reportStateAndNotification

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id",
  "eventId": "unique-event-id",
  "payload": {
    "devices": {
      "notifications": {
        "door-device-id": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "follow-up-token-1"
            }
          }
        }
      },
      "states": {
        "door-device-id": {
          "openPercent": 70
        }
      }
    }
  }
}

O Assistant vai perguntar ao usuário com "o dispositivo está se congestionou" depois de receber a notificação. Você pode enviar o modelo com notificações no mesmo payload.

Para mais informações e detalhes de errorCodes, consulte a Erros e exceções documentação de referência.