Tratar erros e exceções

Quando dispositivos ou 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: 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 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 oferece alguns exemplos de respostas de intent que processam erros. Consulte 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 "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 podem ser controlados. Por isso, 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 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 ainda é necessário enviar o estado off-line dos dispositivos no estado do relatório depois de enviar errorCode deviceOffline na resposta EXECUTE.

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

Um usuário tenta trancar a fechadura inteligente da porta da frente usando o Assistant. Você consegue controlar a trava, mas percebe que a bateria do dispositivo está baixa. Por isso, seu atendimento 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" depois de receber a resposta.

Exemplo 3: notificações proativas de erros

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

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

Exemplo 4: notificação de acompanhamento

Para comandos de traços 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 travada 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 que "o dispositivo está travado" depois de receber a notificação. É possível enviar os estados de dispositivo correspondentes com notificações no mesmo payload.

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