Solucionar erros e exceções

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

Este guia fornece alguns exemplos de respostas de intent que manipulam erros. Consulte Erros e exceções para revisar os valores errorCode válidos para erros e exceções.

Exemplo 1: resposta de erro para o intent EXECUTE

O usuário final tem duas lâmpadas inteligentes e está instalada na sala de estar. O usuário emite um comando "acenda 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 são controláveis. Portanto, o fulfillment retorna uma resposta de EXECUTE com status ERROR e errorCode deviceOffline.

Este exemplo demonstra como retornar uma resposta EXECUTE com um 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 solicitará que o usuário "o dispositivo não esteja disponível no momento" 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 o intent EXECUTE

Um usuário tenta trancar o Smart Lock na porta da frente usando um dispositivo com Assistant. Você pode controlar o bloqueio, mas a bateria do dispositivo está acabando, então 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 solicitará ao usuário que "o dispositivo esteja com a bateria baixa" 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, especialmente para funções que os usuários esperam realizar automaticamente. Para características compatíveis com notificações proativas, você pode notificar o usuário proativamente enquanto ocorre um erro se você tiver implementado smart home notificações proativas.

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

Exemplo 4: notificação de acompanhamento

Para comandos de traços compatíveis com notificações de acompanhamento, é possível enviar uma notificação de acompanhamento ao usuário enquanto ocorre um erro ou uma exceção, caso você tenha implementado smart home notificações de acompanhamento.

Um usuário emite um comando para fechar a porta da garagem, mas a porta está emperrada ao fechá-la. 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 solicitará que o usuário "o dispositivo esteja interrompido" depois de receber a notificação. Você pode enviar os estados correspondentes do dispositivo com notificações no mesmo payload.

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