Tratar erros e exceções

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

Este guia oferece alguns exemplos de respostas de intents que tratam erros. Consulte os Erros e exceções para analisar os valores errorCode válidos 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 "acender as luzes da sala de estar", e o Google enviou 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, 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. Lembre-se de que ainda é necessário enviar o estado off-line dos dispositivos no estado do relatório após enviar errorCode deviceOffline na resposta EXECUTE.

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

Um usuário tenta bloquear a fechadura inteligente da porta da frente usando Assistant. Você pode controlar o bloqueio, 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 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 tem bateria fraca" 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 eles esperam que sejam concluídas automaticamente. Para características que oferecem suporte a notificações proativas, você pode notificar o usuário de forma proativa quando ocorre um erro, se tiver implementado smart home notificações proativas.

Uma secadora inteligente está funcionando, e alguém abre a porta antes que o ciclo termine. Você pode chamar o Google Home Graph API reportStateAndNotifications método 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 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 solicita ao usuário "a porta do dispositivo está aberta" após receber a notificação. Você pode enviar os estados de dispositivo correspondentes junto com as notificações no mesmo payload.

Exemplo 4: notificação de acompanhamento

Para comandos de características que oferecem suporte a notificações de acompanhamento, você pode enviar uma notificação de acompanhamento ao usuário quando ocorre um erro ou uma exceção, se tiver implementado smart home notificações de acompanhamento.

Um usuário emite um comando para fechar a porta da garagem, mas ela fica presa 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á preso" após receber a notificação. Você pode enviar os estados de dispositivo correspondentes com notificações no mesmo payload.

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