欢迎使用 Google Home 开发者中心,您可以在这里学习有关如何开发智能家居 Action 的新平台。注意:你将继续在 Actions 控制台中构建操作。

第二层用户身份验证

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

通过第二层用户身份验证,您可以为语音指令添加双重身份验证。这可让您为特定操作增加额外的安全保障,如关闭监控摄像头或开门。第二层用户身份验证与特定的设备特征并无关联,这让你能够决定何时让 Google 助理发出质询。例如,你可以选择针对监控摄像头的 OnOff 特征发出质询,但不针对灯的 OnOff 特征发出质询。在某些情况下,你可能还会让 Google 助理针对同一项操作发出质询。例如,你可以请求 Google 助理在 NFC 遥控钥匙不在门附近时发出开门的质询请求,但在钥匙存在时不发出质询请求。

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

Google 助理使用对话框发出质询,但如果你在非语音界面上使用 Google 助理,PIN 码和确认信息会在屏幕上显示。

支持的设备类型

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

支持的设备特征

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

支持的质询类型

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

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

无质询

此示例展示了成功的 EXECUTE 请求和响应,没有对开灯的质询。

User 开灯
Google 助理 好,正在开这 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 助理 正在把客厅灯调暗。确定吗?
用户 是。
Google 助理 正在把客厅灯调暗。
请求 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 均已设置,那么 Google 助理可以询问“确定要将空调的供暖温度设为 28 度吗?”

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

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

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

User 将空调模式设为供暖模式。
Google 助理 确定要把空调的供暖温度设为 28 度吗?
用户 是。
Google 助理 正在将空调的供暖温度设为 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 质询的响应,因此 Google 助理会请求获取 PIN 码。此时,用户可以提供错误或有效的 PIN 码。

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

用户 开门。
Google 助理 能告诉我你的安全码吗?
请求
{
  "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 类型时,Google 助理会再次询问安全码。如果用户失败的次数过多,你可以返回 tooManyFailedAttempts 错误响应。请参阅错误响应

User 333222
Google 助理 抱歉,这个安全码不正确。 能告诉我你的安全码吗?
请求
{
  "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 助理 正在开门。
请求
{
  "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
      }
    }]
  }
}
User 把客厅的灯光调暗。
Google 助理 能告诉我你的安全码吗?
请求
{
  "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 - 好的。

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