Tratar erros e exceções

Quando dispositivos ou solicitações não funcionam como esperado, é importante oferecer uma boa comunicação e tratamento de erros para que os usuários entendam o que aconteceu e, sempre que possível, como corrigir o problema. Pense em possíveis cenários de falha e como seu dispositivo precisa responder: e se um usuário interromper uma tarefa em andamento? E se um usuário solicitar uma ação em um dispositivo enquanto ele estiver off-line? Planejar esses problemas e ajudar o usuário a se recuperar deles pode evitar a frustração do usuário e criar uma experiência de maior qualidade para seus dispositivos.

Este guia apresenta alguns exemplos de respostas de intent que processam erros. Consulte os Erros e exceções para analisar 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 envia uma intent EXECUTE para o URL de fulfillment. Você descobriu que os dispositivos do usuário estão off-line e não são controláveis. Portanto, o fulfillment retorna uma resposta EXECUTE com status ERROR e errorCode deviceOffline.

Este exemplo demonstra como retornar uma resposta EXECUTE com um errorCode de um dispositivo de luz, 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 solicita ao usuário "o dispositivo não está disponível no momento" após receber a resposta. Não se esqueça de que você ainda precisa enviar o estado off-line para dispositivos no estado de relatório depois de enviar errorCode deviceOffline na resposta EXECUTE.

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

Um usuário tenta trancar a fechadura inteligente da porta da frente usando Assistant. Você pode controlar a fechadura, mas a bateria do dispositivo está fraca. Portanto, a resposta de fulfillment retorna uma resposta EXECUTE com status SUCCESS e exceptionCode lowBattery.

Este exemplo demonstra como enviar uma resposta EXECUTE com um exceptionCode de um dispositivo de bloqueio, 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 solicita ao usuário "o dispositivo está com pouca bateria" após receber a resposta.

Exemplo 3: notificações de erro proativas

Em alguns casos, pode ser útil alertar os usuários sobre um erro, principalmente para funções que os usuários esperam que sejam concluídas automaticamente. Para recursos que ofereçam suporte a notificações proativas, você pode notificar o usuário proativamente enquanto um erro acontece se tiver implementado smart home notificações proativas.

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

Este exemplo demonstra como enviar uma notificação proativa com um errorCode de um dispositivo de secagem, 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 solicita ao usuário "a porta do dispositivo está aberta" após receber a notificação. É possível enviar os estados do dispositivo correspondentes com notificações no mesmo payload.

Exemplo 4: notificação de acompanhamento

Para comandos de atributos que oferecem suporte a notificações de acompanhamento, é possível enviar uma notificação de acompanhamento ao usuário enquanto um erro ou uma exceção acontece, se você tiver implementado smart home notificações de acompanhamento.

Um usuário emite um comando para fechar a porta da garagem, mas ela fica presa enquanto fecha. 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 solicita ao usuário "o dispositivo está bloqueado" após receber a notificação. É possível enviar os estados do dispositivo correspondentes com notificações no mesmo payload.

Para mais informações e detalhes sobre errorCodes, consulte a documentação de referência Errors and exceptions.