Secondary User Verification

二次的なユーザー確認では、音声コマンドに 2 要素目のセキュリティを追加できます。これにより、セキュリティ カメラをオフにする操作やドアを開ける操作など、特定の操作に対するセキュリティを強化できます。二次的なユーザー確認は特定のデバイス トレイトに関連付けられないため、Google Assistant にチャレンジを発行するタイミングを決定できます。たとえば、セキュリティ カメラの OnOff トレイトではチャレンジを発行し、ライトの OnOff トレイトではチャレンジを発行しないようにできます。また、同じアクションの特定の状況で Assistant 問題チャレンジを行うこともできます。たとえば、NFC キーフォブがドアの近くにない場合はドアを開けるチャレンジ リクエストを発行し、キーフォブがある場合にはチャレンジを発行しないよう Assistant にリクエストできます。

Assistant は、明示的な確認応答と個人識別番号（PIN）の 2 種類のチャレンジを発行できます。これにより、Assistant からアクションに送信される QUERY インテントと EXECUTE インテントにチャレンジ ブロックが追加され、challengeNeeded エラー レスポンスが受け入れられます。Assistant は、チャレンジ ブロックにチャレンジ データを格納したインテント リクエストをアクションに返します。その後、チャレンジ データを検証して、ユーザーが正しいセキュリティ レスポンスを返したかどうかを判断できます。

Assistant はダイアログを使用してチャレンジを発行しますが、音声以外のサーフェスで Assistant を使用すると、PIN と確認は画面上で行われます。

サポートされているデバイスタイプ

Secondary User Verification はすべてのデバイスタイプでサポートされています。

サポートされているデバイス トレイト

Secondary User Verification はすべてのデバイス トレイトでサポートされています。

サポートされているチャレンジの種類

Secondary User Verification がサポートされているチャレンジの種類は以下のとおりです。

  • チャレンジなし - Secondary User Verification チャレンジを使用しないリクエストとレスポンス。
  • 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 に特定のアクションを実行させることもできます。

次のトレイトとその状態は、トレイトの状態を持つ ackNeeded をサポートします。特定のトレイトのリストは、そのすべての状態がサポートされていることを示します。

以下の例は、トレイトの状態を使用した ackNeeded チャレンジを含むリクエストとレスポンスを示しています。エアコンのモードを暖房に切り替え、温度を 28 度に設定します。次に、Assistant はユーザーに、暖房をオンにして温度を 28 度に設定することの確認を求めます。これは、レスポンスで 28 の thermostatTemperatureSetpoint が状態として返されるためです。

ユーザー AC モードを暖房に設定します。
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"
      }
    }]
  }
}

Error responses（エラー応答）

以下は、レスポンスで返される可能性があるエラーコードです。

  • tooManyFailedAttempts - 試行回数が上限に達しました。この操作を完了するには、デバイスのアプリに移動してください。
  • pinIncorrect - セキュリティ コードが正しくありません。
  • userCancelled - OK

エラーと例外の全リストをご覧ください。