欢迎使用 Google Home 开发者中心，这是一个学习如何开发智能家居 Action 的新平台。注意：构建 Action 的工作仍需在 Actions 控制台中完成。

此页面由 Cloud Translation API 翻译。

第二层用户身份验证

通过第二层用户身份验证，您可以为语音添加第二重身份验证命令。这让您可以为某些操作增加额外的安全性，例如关闭监控摄像头或开门。第二层用户身份验证现为并不与特定设备特征相关联，这让您可以决定何时 Google Assistant发起挑战。例如，您可以选择针对 OnOff 特征发起质询但对于监控摄像头， OnOff 特征点。你还可以使用Assistant 特定情况下针对同一 Action 的问题。例如，您可以请求Assistant向如果 NFC 遥控钥匙不在门附近，但却没有打开门，如果存在密钥卡，则发出质询。

Assistant 可以发出两种类型的验证：明确的确认码或个人识别码 (PIN)。这会将向 QUERY 和 EXECUTE intent 发回的质询块从 Assistant 发回给您的 Action 并接受 challengeNeeded 错误响应。然后，Assistant 会将 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

可以使用状态的次要用户确认身份验证 trait。例如，如果您正在与 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 度自 thermostatTemperatureSetpoint 为 28 时，以状态形式返回。

用户	将空调模式设为供暖模式。
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 码的请求和响应示例：

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 - 确定

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