Secondary User Verification

二次的なユーザー確認とは、2 つ目の要素を使って音声コマンドのセキュリティを強化する仕組みです。たとえば、セキュリティ カメラの電源を切る、ドアを開けるといった特定のアクションのセキュリティを強化できます。二次的なユーザー確認 は特定のデバイス トレイトには結び付けられていないため、いつ Google Assistant にチャレンジを発行させるかはデベロッパーが決定できます。たとえば、セキュリティ カメラの OnOff トレイトではチャレンジを発行し、ライトの OnOff トレイトではチャレンジを発行しないようにすることができます。また、同じアクションにおいて、ある特定の状況に限り Assistant にチャレンジを発行させることもできます。たとえば、NFC キーフォブが近くにないドアを開ける場合はチャレンジ リクエストを発行し、キーフォブが存在するドアを開ける場合はチャレンジを発行しないよう Assistant に要求できます。

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

Assistant では、ユーザーへのチャレンジは対話として行われますが、音声非対応のサーフェスで Assistant を使用している場合、PIN の入力と確認は画面上で行われます。

二次的なユーザー確認を使用するタイミング

二次的なユーザー確認 は、任意のデバイスタイプまたはトレイトで有効にできます。ただし、統合の認定を受けるには、特定のセキュリティに配慮したデバイスタイプとトレイトに対して二次的なユーザー確認を実装する必要があります。

次の特性とデバイスの種類の組み合わせでは、pinNeeded チャレンジ タイプを使用したセカンダリ ユーザー認証が必要です。

  • デバイスタイプが CAMERA の場合の OnOff トレイト。
  • デバイスタイプが DOOR、GARAGE、GATE、WINDOW の場合は OpenClose トレイト。
  • ロック解除時の LockUnlock トレイト。
  • 武装解除または武装解除の取り消し時の ArmDisarm トレイト。
  • デバイスタイプが NETWORK または ROUTER の場合、Reboot、SoftwareUpdate、または NetworkControl トレイト。

デバイスタイプが AC_UNIT で、統合が日本国内の地域の場合、TemperatureSetting トレイトには ackNeeded チャレンジ タイプが必要です。

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

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 をサポートします。トレイトだけが記載されている場合は、そのすべての状態がサポートされていることを示します。

  • ArmDisarm
    • ackNeeded チャレンジ タイプを使用して、デバイスの武装または武装の解除を行いますが、武装解除と武装解除のキャンセル機能には pinNeeded チャレンジ タイプが必要です。
  • Fill
  • LockUnlock
    • デバイスをロックするには ackNeeded チャレンジ タイプを使用し、ロックを解除するには pinNeeded チャレンジ タイプを使用します。
  • OnOff
    • on
    • このトレイトには ackNeeded チャレンジ タイプを使用します。このトレイトを CAMERA デバイスで使用する場合は、pinNeeded チャレンジ タイプが必要です。
  • OpenClose
    • このトレイトには ackNeeded チャレンジ タイプを使用します。このトレイトを DOOR、GARAGE、GATE、WINDOW デバイスで使用する場合は、pinNeeded チャレンジ タイプが必要です。
  • Scene
  • TemperatureSetting
    • thermostatMode
    • thermostatTemperatureSetpoint
    • thermostatTemperatureSetpointHigh
    • thermostatTemperatureSetpointLow

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

ユーザー エアコンを暖房に設定して。
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 を提供する可能性があります。

正しくない 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 - わかりました

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