通过第二层用户身份验证,你可以为语音指令添加第二重身份验证。这样一来,您可以针对特定操作增加额外的安全保障,例如关闭监控摄像头或开门。第二层用户身份验证与特定的设备特征并无关联,这让你决定何时可以使用 Google Assistant issue a challenge. For example, you can choose to issue a challenge for the OnOff trait for a security camera, but not issue a challenge for the OnOff trait for a light. You can also have Assistant issue challenges in certain situations for the same action. For example, you can request that Assistant issue a challenge request to open a door if an NFC keyfob is not in the proximity of that door, but not issue a challenge if the keyfob is present.
Assistant 可以发出两种类型的质询:显式确认或个人识别码 (PIN)。这会向从 Assistant 发回到您的操作的 QUERY
和 EXECUTE
intent 添加质询代码块,并接受 challengeNeeded
错误响应。然后,Assistant 会向 intent 请求发送 intent 请求,其中包含质询代码块中的质询数据。然后,您可以验证质询数据,以确定用户是否提供了正确的安全响应。
Assistant 使用对话框发出质询,但是如果您在非语音界面上使用 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 | 正在把客厅灯调暗。 |
{ "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": "ackNeeded" } }] } }
{ "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 } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["123"], "status": "SUCCESS" }] } }
使用特征状态的 ackNeeded
此第二层用户确认身份验证可以针对一个特征使用多个状态。例如,如果你使用的是 TemperatureSetting 特征,并且 thermostatMode
和 thermostatTemperatureSetpoint
均已设置,那么 Assistant 可能会询问“你确定要把空调的供暖温度设为 28 度吗?
您还可以在响应中包含一个状态,使 Assistant 根据给定请求执行特定的操作。
以下特征和状态支持具有特征状态的 ackNeeded
。列出特定特征表示支持其所有状态。
- ArmDisarm
currentArmLevel
currentStatusReport
- Fill
- LockUnlock
- OnOff
on
- OpenClose
- Scene
- TemperatureSetting
thermostatMode
thermostatTemperatureSetpoint
thermostatTemperatureSetpointHigh
thermostatTemperatureSetpointLow
此示例展示了包含一个使用特征状态的 ackNeeded
质询的请求和响应。这会将空调模式更改为供暖模式,并将温度设为 28 度。然后,Assistant 会要求用户确认开启供暖并将温度设置为 28 度,因为 28
的 thermostatTemperatureSetpoint
会作为响应中的状态返回。
用户级 | 将空调模式设为供暖模式。 |
Google Assistant | 确定要把空调的供暖温度设为 28 度吗? |
用户级 | 可以。 |
Google Assistant 分 | 正在将空调的供暖温度设为 28 度。 |
{ "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" } }] }] } }] }
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["123"], "status": "ERROR", "states": { "thermostatMode": "heat", "thermostatTemperatureSetpoint": 28 }, "errorCode": "challengeNeeded", "challengeNeeded": { "type": "ackNeeded" } }] } }
{ "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 } }] }] } }] }
{ "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
- 此 Action 需要一个安全代码,但你尚未在设备的应用中设置该代码。tooManyFailedAttempts
- 抱歉,尝试失败的次数过多。请转到设备的应用中完成这项操作。pinIncorrect
- 抱歉,这个安全码不正确。userCancelled
- 好的。
查看错误和异常的完整列表。