第二层用户身份验证

通过第二层用户身份验证,您可以为语音指令添加第二重身份验证。这样您就可以提高某些操作(例如关闭监控摄像头或开门)的安全性。第二层用户身份验证与特定的设备特征并无关联,这让您能够决定何时让 Google Assistant 发出质询。例如,您可以选择针对监控摄像头的 OnOff 特征发出质询,但不针对灯的 OnOff 特征发出质询。在特定情况下,您还可以针对同一 Action 设置 Assistant 问题验证。例如,您可以请求 Assistant 在 NFC 遥控钥匙不在该门附近时发出开门质询请求,但如果遥控钥匙存在,则不发出质询请求。

Assistant 可以发出两种类型的质询,即显式确认或个人识别码 (PIN)。这会向从 Assistant 发回给您的 Action 的 QUERYEXECUTE intent 添加质询代码块,并接受 challengeNeeded 错误响应。然后,Assistant 将 intent 请求以及质询代码块中的质询数据发回给您的 Action。然后,您可以验证质询数据,以确定用户是否提供了正确的安全响应。

Assistant 使用对话框发出质询,但如果您在非语音 surface 上使用 Assistant,PIN 码和确认信息会在屏幕上显示。

支持的设备类型

所有设备类型都支持第二层用户身份验证。

支持的设备特征

所有设备特征都支持第二层用户身份验证。

支持的质询类型

以下是受支持的第二层用户身份验证质询类型:

  • 无质询 - 此请求和响应不使用第二层用户身份验证质询。
  • ackNeeded - 此第二层用户身份验证需要显式确认(是或否),并且还可以将特征状态作为响应反馈。不建议对安全设备和特征采用此质询类型。
  • pinNeeded - 此第二层用户身份验证要求提供个人识别码 (PIN),非常适合安全设备和特征。

无质询

以下示例展示了在不使用开灯质询的情况下成功实现开灯的 EXECUTE 请求和响应。

用户 开灯
Google Assistant 好,正在开这 3 盏灯。
请求
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.OnOff",
          "params": {
            "on": true
          }
        }]
      }]
    }
  }]
}
响应
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

ackNeeded

此第二层用户确认身份验证可以针对一个特征使用多个状态,或使用简单的确认身份验证。

ackNeeded 质询类型分为以下几种:

简单 ackNeeded

此示例展示了一个简单的请求和响应,包含灯光调暗 ackNeeded 质询和灯光调暗确认。

用户 把客厅的灯光调暗。
Google Assistant 正在把客厅灯调暗。您确定吗?
用户 有。
Google Assistant 正在把客厅灯调暗。
请求 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}
响应 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
请求 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
响应 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

使用特征状态的 ackNeeded

此第二层用户确认身份验证可以针对一个特征使用多个状态。例如,如果您使用的是 TemperatureSetting 特征,并且 thermostatModethermostatTemperatureSetpoint 均已设置,Assistant 可以询问“确定要把空调的供暖温度设为 28 度吗?”

您还可以在响应中添加一个状态,让 Assistant 根据给定请求执行特定的操作。

以下特征和状态支持使用特征状态的 ackNeeded。特定特征列表表示其所有状态均受支持。

以下示例展示了包含使用特征状态的 ackNeeded 质询的请求和响应。它会将空调模式更改为供暖模式,并将温度设为 28 度。然后,Assistant 要求用户确认要开启供暖并将温度设置为 28 度,因为 28thermostatTemperatureSetpoint 会在响应中以状态的形式返回。

用户 将空调模式设为供暖模式。
Google Assistant 确定要把空调的供暖温度设为 28 度吗?
用户 有。
Google Assistantnt 正在将空调的供暖温度设为 28 度。
请求 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          }
        }]
      }]
    }
  }]
}
响应 1
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}
请求 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}
响应 2
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

pinNeeded

建议对安全设备采用 pinNeeded 质询。

以下示例展示了包含 pinNeeded 质询的初始请求和响应。该示例返回了包含 pinNeeded 质询的响应,因此 Assistant 会要求提供 PIN 码。此时,用户可以提供错误或有效的 PIN 码。

错误或有效的 PIN 码的请求和响应示例:

用户 开门。
Google Assistant 能告诉我你的安全码吗?
请求
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          }
        }]
      }]
    }
  }]
}
响应
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

PIN 码不正确

以下示例展示了包含 challengeFailedPinNeeded 质询的请求和响应。您应在初始 pinNeeded 质询失败后使用该质询。

当返回 challengeFailedPinNeeded 类型时,Assistant 会再次要求输入安全码。如果用户失败的次数过多,您可以返回 tooManyFailedAttempts 错误响应。请参阅错误响应

用户 333222
Google Assistant 抱歉,这个安全码不正确。 能告诉我你的安全码吗?
请求
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333222"
          }
        }]
      }]
    }
  }]
}
响应
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

PIN 码有效

此示例展示了有效 PIN 的请求和响应。

用户 333444
Google Assistant 正在开门。
请求
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333444"
          }
        }]
      }]
    }
  }]
}
响应
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}
用户 把客厅的灯光调暗。
Google Assistant 能告诉我你的安全码吗?
请求
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}
响应
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

错误响应

下面是一些可以随响应返回的错误代码:

  • challengeFailedNotSetup - 此操作需要安全码,但您尚未在设备的应用中设置该安全码。
  • tooManyFailedAttempts - 抱歉,尝试失败的次数过多。请前往设备的应用中完成这项操作。
  • pinIncorrect - 抱歉,这个安全码不正确。
  • userCancelled - 好的。

查看错误和异常的完整列表。