Google Home Developer Center へようこそ。スマートホーム アクションの開発方法を学習できます。注: アクションの構築は、引き続き Actions Console で行います。

セカンダリ ユーザーの確認

Secondary User Verification とは、2 つ目の要素を使って音声コマンドのセキュリティを強化する仕組みです。これにより、セキュリティ カメラの電源を切る、ドアを開けるといった特定のアクションのセキュリティを高めることができます。Secondary User Verification は特定のデバイス トレイトには結び付けられていないため、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 - 明示的な確認応答(はい / いいえ)を要求する Secondary User Verification。レスポンス フィードバックとしてトレイトの状態を使用することもできます。このチャレンジ タイプをセキュリティ デバイスやセキュリティ トレイトに使用することはおすすめしません。
  • pinNeeded - 個人識別番号(PIN)を要求する Secondary User Verification。セキュリティ デバイスやセキュリティ トレイトに最適です。

チャレンジなし

以下の例は、チャレンジを使用せずに照明を点灯させる 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 トレイトを使用するときに thermostatModethermostatTemperatureSetpoint の両方が設定されている場合、Assistant に「エアコンの暖房を 28 度に設定してもよろしいですか?」という確認できます。

また、リクエストに対して Assistant が特定のアクションを実行するように、レスポンスに状態を含めることもできます。

以下のトレイトとその状態は、トレイトの状態を伴う ackNeeded をサポートします。トレイトだけが記載されている場合は、そのすべての状態がサポートされていることを示します。

以下の例は、トレイトの状態を使用した ackNeeded チャレンジでのリクエストとレスポンスを示しています。エアコンモードを暖房に切り替え、温度を 28 度に設定します。レスポンスで状態として thermostatTemperatureSetpoint28 として返されるため、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 が提供された場合のリクエストとレスポンスの例:

ユーザー ドアのロックを解除して。
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(エラー応答)

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

  • challengeFailedNotSetup - この操作にはセキュリティ コードが必要ですが、デバイスのアプリにセキュリティ コードが設定されていません。
  • tooManyFailedAttempts -試行回数が上限を超えました。デバイスのアプリで操作を完了してください。
  • pinIncorrect - セキュリティ コードが正しくありません。
  • userCancelled - わかりました。

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