此页面由 Cloud Translation API 翻译。

第二层用户身份验证

通过第二层用户身份验证，你可以为语音指令添加第二重身份验证。这样一来，您可以针对特定操作增加额外的安全保障，例如关闭监控摄像头或开门。第二层用户身份验证与特定的设备特征并无关联，这让你决定何时可以使用 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

简单 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 特征，并且 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 度。

请求 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 码的请求和响应示例：

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 - 好的。

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