第二层用户身份验证

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

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

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 正在把客厅灯调暗。
请求 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 根据给定请求执行特定的 Action。

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

以下示例展示了包含一个使用特征状态的 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 码的请求和响应示例：

用户 开门。
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"
      }
    }]
  }
}

错误响应

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

  • tooManyFailedAttempts - 抱歉，尝试失败的次数过多。 请前往设备的应用中完成此操作。
  • pinIncorrect - 抱歉，这个安全码不正确。
  • userCancelled - 确定

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