歡迎來到 Google Home 開發人員中心,你可以在這裡學習如何學習智慧型住宅動作。注意事項:您將在 Actions 主控台建構動作。

次要使用者驗證

次要使用者驗證功能可讓您在語音指令中加入第二重安全性機制。因此,您可以針對特定動作 (例如關閉保全攝影機或打開車門) 增添額外安全。次要使用者驗證不會與特定裝置特性相關聯,因此您可以決定何時要發出 Google Assistant 問題。舉例來說,您可以選擇針對保全相機發出 OnOff 特徵的問題,但不要對光源的 OnOff 特性發出問題。在某些情況下,Assistant 也可能會面臨相同的動作。舉例來說,如果 Assistant 代表遙控未位於該門口的附近,您可以要求發出車鑰開啟問題的要求,但無法發出問題。

Assistant 可提出兩種挑戰:明確確認碼或個人識別碼 (PIN 碼)。這樣做會將一個驗證區塊新增至 QUERYEXECUTEAssistant 意圖傳送至您的動作,並接受 challengeNeeded 錯誤回應。接著,Assistant 會將意圖要求與挑戰資料中的挑戰資料一起傳回。接著,您就能驗證挑戰資料,判斷使用者是否提供正確的安全性回應。

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 挑戰來調暗燈光,以及確認調暗燈光。

使用者 調暗客廳的燈
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"
    }]
  }
}

陷入困境

次要使用者確認狀態,可使用狀態進行交易。舉例來說,如果您使用的是 TemperatureSetting 特徵,且 thermostatModethermostatTemperatureSetpoint 都設定完成,Assistant 會詢問 您是否確定要將空調機的暖氣設為 28 度?

您也可以在回應中加入狀態,讓 Assistant 根據指定要求執行特定動作。

以下特性和狀態支援具有特性的 ackNeeded。特定特性的清單表示其所有狀態都受到支援。

這個範例說明要求和回應,其中包含使用特性的 ackNeeded 挑戰。這會改變空調模式的溫度,並將溫度設為 28 度。接著,Assistant 會要求使用者確認開啟暖氣,並將溫度設為 28 度,因為回應中傳回 28thermostatTemperatureSetpoint

使用者 將空調模式設為暖氣。
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 驗證的回應,因此 Assistant 會要求提供 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 - 這個動作需要安全碼,但你尚未在裝置應用程式中進行設定。
  • tooManyFailedAttempts - 抱歉,失敗的次數過多。請前往裝置上的應用程式完成這項操作。
  • pinIncorrect - 抱歉,安全碼不正確。
  • userCancelled - 確定

請參閱錯誤和例外狀況的完整清單。