Tratar erros e exceções

Quando os dispositivos ou as solicitações não funcionam como esperado, é importante fornecer um bom tratamento de erros e uma boa comunicação 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 o dispositivo deve responder: e se um usuário interromper uma tarefa em andamento? E se um usuário solicitar uma ação de um dispositivo enquanto ele estiver off-line? Planejar-se para esses problemas e ajudar o usuário a se recuperar deles pode evitar frustrações e criar uma experiência de maior qualidade para seus dispositivos.

Este guia mostra alguns exemplos de respostas de intent que lidam com erros. Consulte Erros e exceções para revisar 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 iluminações inteligentes instaladas na sala de estar. O usuário emite um comando "acender 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 podem ser controlados. Portanto, seu 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 iluminação, 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 mostra ao usuário a mensagem "o dispositivo não está disponível em tempo real" depois de receber a resposta. Lembre-se de que você ainda precisa enviar o estado off-line para dispositivos no estado do relatório depois de enviar errorCode deviceOffline na resposta EXECUTE.

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

Um usuário tenta trancar a fechadura inteligente da porta da frente usando o Assistant. Você consegue controlar a fechadura, mas descobre que a bateria do dispositivo está fraca. Portanto, o 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 fechadura, 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 mostra ao usuário a mensagem "o dispositivo está com pouca bateria" depois de receber a resposta.

Exemplo 3: notificações proativas de erro

Em alguns casos, pode ser útil alertar os usuários sobre um erro, principalmente para funções que eles esperam que sejam concluídas automaticamente. Para características que oferecem suporte a notificações proativas, é possível notificar o usuário de forma proativa enquanto um erro acontece se você tiver implementado as smart home notificações proativas.

Uma secadora inteligente está funcionando, e alguém abre a porta antes que o ciclo termine. Chame 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 uma 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 mostra ao usuário a mensagem "A porta do dispositivo está aberta" depois de receber a notificação. É possível enviar os estados correspondentes do dispositivo junto com as notificações no mesmo payload.

Exemplo 4: notificação de acompanhamento

Para comandos de atributos que aceitam notificações de acompanhamento, é possível enviar uma notificação de acompanhamento ao usuário quando ocorre um erro ou uma exceção, se você tiver implementado as smart home notificações de acompanhamento.

Um usuário emite um comando para fechar o portão da garagem, mas ele emperra 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 solicita ao usuário "o dispositivo está bloqueado" depois de receber a notificação. É possível enviar os estados correspondentes do dispositivo com notificações no mesmo payload.

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