Alexaスキルで音声による同意確認を使用する

Note: Sign in to the developer console to build or publish your skill.

スキルにユーザーの情報が必要な場合、スキルとの情報共有にユーザーが口頭で同意できるようにすることができます。たとえば、以下のやり取りでは、ユーザーはタクシー予約スキルに名前、現在地、携帯電話番号へのアクセスを許可することに同意しています。

ユーザー： アレクサ、タクシー予約を開いて。
Alexa： タクシー予約へようこそ。どこに行きますか？
ユーザー： 東京スカイツリー。
Alexa： わかりました。車を手配するには、お名前、現在地、携帯電話番号が必要です。
Alexa： タクシー予約に、お名前、現在地、携帯電話番号へのアクセスを許可しますか？「許可します」または「いいえ」でお答えください。
ユーザー： 許可します。
Alexa： ありがとうございます。現在地から東京スカイツリーまでの乗車料金は1,500円、お迎えまでの所要時間は10分です。予約しますか？
ユーザー： はい。
Alexa： わかりました。タクシーは10分で到着します。

ユーザーが音声で権限を付与しない場合は、Alexaアプリを使用して後から権限を付与できます。スキルは、このような場合のフォールバックワークフローを提供する必要があります。

リクエストされたユーザー情報の種類によっては、PINやワンタイムパスワードなど、ユーザーによる追加の確認が必要になることがあります。この確認には、ユーザーをAlexaアプリにリダイレクトするプロセスが含まれる場合もあります。これらの詳細はスキルで処理する必要はありません。スキルで必要なのは、Alexaが返す結果を確認し、適切に処理することだけです。

スキル権限の概要
前提条件
音声による同意確認の標準ワークフロー
音声による同意確認フローの開始方法
音声による同意確認フローの後に制御を再開する方法
スキルに音声による同意確認を実装する手順
関連トピック

スキル権限の概要

スキル権限は、ユーザーの名前や電話番号など、1つのユーザー情報を表します。プログラムの観点から見ると、各権限は「権限スコープ」に関連付けられています。

以下の表は、権限に関する次の情報を示しています。

音声による同意確認で利用できる権限。
音声による同意確認フローを開始するためにディレクティブで使用する関連スコープ。
利用可能な同意レベル。権限を利用できるのがAmazonアカウントレベルか、識別された発話者（個人）レベルか、またはその両方かを示します。たとえば、「alexa::profile:name:read」という権限は、Echoデバイスが登録されているAmazonアカウントの名前、または識別された発話者の名前を表すことができます。識別された発話者の詳細については、Alexaスキルのパーソナライズを参照してください。

権限	スコープ	同意レベル
名前	`alexa::profile:given_name:read`	アカウントレベルと個人レベル
姓名	`alexa::profile:name:read`	アカウントレベルと個人レベル
携帯電話番号	`alexa::profile:mobile_number:read`	アカウントレベルと個人レベル
メール	`alexa::profile:email:read`	アカウントレベルのみ
郵便番号	`alexa:devices:all:address:country_and_postal_code:read`	アカウントレベルのみ
位置情報	`alexa::devices:all:geolocation:read`	アカウントレベルのみ
タイマー	`alexa::alerts:timers:skill:readwrite`	アカウントレベルのみ
リマインダー	`alexa::alerts:reminders:skill:readwrite`	アカウントレベルのみ

前提条件

音声による同意確認を使用するには、スキルが次の要件を満たす必要があります。

カスタムスキルである必要があります。
子ども向けスキルでは使用できません。
（Alexaに話しかけている個人とは異なる可能性もあるアカウント所有者ではなく）識別された発話者の情報が必要な場合は、スキルがパーソナライズをサポートしている必要があります。

音声による同意確認の標準ワークフロー

スキルは、ユーザー情報が必要な状況になった場合、起動リクエストで渡されたアクセストークンを使用して、ユーザー情報にアクセスしようとします。対象のデータ（ユーザーの名前など）にアクセスする権限がアクセストークンに含まれていない場合、スキルがデータを取得しようとするとエラーが発生します。この時点で、スキルはSkill Connectionsと呼ばれるAlexa機能を使用してAmazonが所有する音声同意確認スキルに制御を渡すことにより、音声による同意確認プロセスを開始します。Alexaはユーザーとやり取りして音声による同意確認プロセスを処理し、成功または失敗のステータスで制御をスキルに戻します。これにより、スキルは結果を適切に処理できます。

以下は、音声による同意確認の標準ワークフローの例です。例では、Amazon所有の音声同意確認スキルに開発者のスキルが制御を渡すポイントと、Amazon所有のスキルが開発者のスキルに制御を戻すポイントを示しています。

これらの例は、デモンストレーションのみを目的としています。音声による同意確認の実装時にスキルのダイアログは変更できますが、AlexaのダイアログはAmazonによって制御されます。

ユーザーが情報共有に同意した場合

以下の例は、ユーザーがタクシー予約スキルと情報を共有することに同意した場合の動作を示しています。

ステップ	発話者	音声またはアクション
1	ユーザー	「アレクサ、タクシー予約を開いて」
2	Alexa（開発者のスキル）	「タクシー予約へようこそ。どこに行きますか？」
3	ユーザー	「東京スカイツリー」
4	Alexa（開発者のスキル）	「わかりました。車を手配するには、お名前、現在地、携帯電話番号が必要です」
5	なし	スキルが`Connections.StartConnection`ディレクティブを送信し、Skill Connectionsを介してAlexaに制御を渡します。
6	Alexa（Amazon所有のスキル）	「タクシー予約に、お名前、現在地、携帯電話番号へのアクセスを許可しますか？『許可します』または『いいえ』でお答えください」
7	ユーザー	「許可します」
8	なし	ユーザー情報の種類によっては、ここで確認フローが追加される場合があります。たとえば、AlexaがユーザーにPINまたはワンタイムパスワードを要求する場合があります。
9	なし	Alexaがスキルに`SessionResumedRequest`リクエスト（ステータスは`ACCEPTED`）を送信し、制御をスキルに戻します。
10	Alexa（開発者のスキル）	「ありがとうございます。現在地から東京スカイツリーまでの乗車料金は1,500円、お迎えまでの所要時間は10分です。予約しますか？」
11	ユーザー	「はい」
12	Alexa（開発者のスキル）	「わかりました。タクシーは10分で到着します。」

ユーザーが情報共有を拒否した場合

以下の例は、ユーザーがタクシー予約スキルと情報を共有することを明示的に拒否した場合の動作を示しています。

ステップ	発話者	音声またはアクション
1	ユーザー	「アレクサ、タクシー予約を開いて」
2	Alexa（開発者のスキル）	「タクシー予約へようこそ。どこに行きますか？」
3	ユーザー	「東京スカイツリー」
4	Alexa（開発者のスキル）	「わかりました。車を手配するには、お名前、現在地、携帯電話番号が必要です」
5	なし	スキルが`Connections.StartConnection`ディレクティブを送信し、Skill Connectionsを介してAlexaに制御を渡します。
6	Alexa（Amazon所有のスキル）	「タクシー予約に、お名前、現在地、携帯電話番号へのアクセスを許可しますか？『許可します』または『いいえ』でお答えください」
7	ユーザー	「いいえ」
8	なし	Alexaがスキルに`SessionResumedRequest`リクエスト（ステータスは`DENIED`）を送信し、制御をスキルに戻します。
9	Alexa（開発者のスキル）	（`DENIED`ステータスの処理）「わかりました。タクシー予約で車を手配するには、この情報へのアクセス権限が必要です。Alexaアプリでタクシー予約に権限を付与してから、再度タクシー予約を開いてください。タクシー予約をご利用いただきありがとうございます」

ユーザーが質問に答えない場合

以下の例は、ユーザーが音声による同意確認に応答しない場合の動作を示しています。

ステップ	発話者	音声またはアクション
1	ユーザー	「アレクサ、タクシー予約を開いて」
2	Alexa（開発者のスキル）	「タクシー予約へようこそ。どこに行きますか？」
3	ユーザー	「東京スカイツリー」
4	Alexa（開発者のスキル）	「わかりました。わかりました。車を手配するには、お名前、現在地、携帯電話番号が必要です」
5	なし	スキルが`Connections.StartConnection`ディレクティブを送信し、Skill Connectionsを介してAlexaに制御を渡します。
6	Alexa（Amazon所有のスキル）	「タクシー予約に、お名前、現在地、携帯電話番号へのアクセスを許可しますか？『許可します』または『いいえ』でお答えください」
7	ユーザー	ユーザーが応答せず、Alexaが8秒後にタイムアウトします。
8	なし	Alexaがスキルに`SessionResumedRequest`リクエストを送信し、スキルに制御を戻します。このリクエストは、ステータスが`NOT_ANSWERED`のコード200、または「`(NO CONTENT/CANCELLED) THE SKILL SESSION WAS ENDED BY THE USER`」というメッセージを含むコード204である場合があります。
9	Alexa（開発者のスキル）	（権限がない場合の処理）「タクシー予約で車を手配するには、この情報へのアクセス権限が必要です。Alexaアプリでタクシー予約に権限を付与してから、再度タクシー予約を開いてください。タクシー予約をご利用いただきありがとうございます」

音声による同意確認フローの開始方法

ユーザー情報を必要とするリクエストをユーザーが行ったら、応答オブジェクトでConnections.StartConnectionディレクティブを返すことにより、スキルからAlexaにコントロールを渡します。スキルコードでConnections.StartConnectionディレクティブを返すときは、shouldEndSessionフラグを未定義のままにする必要があります。

Connections.StartConnectionディレクティブ内のフィールドについての説明は、Connections.StartConnection directive schemaを参照してください。

以下の例は、Alexaに制御を渡すためにスキルが使用するConnections.StartConnectionディレクティブを示しています。このディレクティブは、Alexaからのリクエストに対する応答に含めます。Alexaのリクエストおよび応答のフォーマットについて詳しくは、カスタムスキルのJSONインターフェースのリファレンスを参照してください。Skill Connectionsの使用方法の詳細については、Skill Connectionsを使用したタスクのリクエストを参照してください。

Raw JSON
Node.js SDK v2

クリップボードにコピーされました。

{
   "type": "Connections.StartConnection",
   "uri": "connection://AMAZON.AskForPermissionsConsent/2",
   "input": {
      "@type": "AskForPermissionsConsentRequest",
      "@version": "2",
      "permissionScopes": [
        {
           "permissionScope": "<権限スコープ>", // alexa::profile:name:readなど
           "consentLevel": "ACCOUNT" // またはPERSON
        },
        {
           "permissionScope": "<別の権限スコープ>", // alexa::devices:all:geolocation:readなど
           "consentLevel": "ACCOUNT" // またはPERSON
        },
        ...
      ]
   },
   "token": "example-token"
}                    

クリップボードにコピーされました。

このサンプルコードはAlexa Skills Kit SDK for Node.js（v2）を使用しています。

return handlerInput.responseBuilder
   .addDirective({
      'type': 'Connections.StartConnection',
      'uri': 'connection://AMAZON.AskForPermissionsConsent/2',
      'input': {
         '@type': 'AskForPermissionsConsentRequest',
         '@version': '2',
         'permissionScopes': [
           {
              'permissionScope': '<権限スコープ>', // alexa::profile:name:readなど
              'consentLevel': 'ACCOUNT' // またはPERSON
           },
           {
              'permissionScope': '<別の権限スコープ>', // alexa::devices:all:geolocation:readなど
              'consentLevel': 'ACCOUNT' // またはPERSON
           },
           ...
         ]
      },
      'token': 'example-token'
   })
   .getResponse();

音声による同意確認フローの後に制御を再開する方法

ユーザーから同意を得ようと試みた後、Alexaは音声による同意確認の結果を含むSessionResumedRequestをスキルに送信します。SessionResumedRequestのrequestオブジェクト内のフィールドに関する説明については、SessionResumedRequest schemaを参照してください。

以下の例は、スキルがAlexaから受け取るSessionResumedRequestイベントを示しています。

Raw JSON
Node.js SDK v2

クリップボードにコピーされました。

{
   "context": {
      ....
   },
   "request": {
      "type": "SessionResumedRequest",
      ....
      "cause": {
         "type": "ConnectionCompleted",
         "token": "some connection token data",
         "status": {
            "code": "200",
            "message": "Ok."
         },
         "result": {
            "permissionScopes" : [
             {
                "permissionScope" : "<外部権限スコープ名>",
                "consentLevel": "<同意レベルの列挙型>",
             },
            ],
            "status" : <権限ステータスの列挙型>
         }
      }
   }
}

クリップボードにコピーされました。

このサンプルコードはAlexa Skills Kit SDK for Node.js （v2）を使用しています。

/**
 * SessionResumedRequestを処理するハンドラー。
 */
const SessionResumedRequestHandler = {
    canHandle(handlerInput) {
        const request = handlerInput.requestEnvelope.request;
        return request.type === 'SessionResumedRequest';
    },
    handle(handlerInput) {
        const connectionsStatus = handlerInput.requestEnvelope.request.cause.status;
        const connectionsCode = connectionsStatus.code;
        const person = handlerInput.requestEnvelope.context.System.person;

        // まず、Skill Connectionsの試行が正常に完了したかどうかを確認します。
        // タスクが成功したかどうかはわからないため、タスクの結果は次に確認します。
        if ((connectionsCode != 200) && (connectionsCode != 204)) {
            return handlerInput.responseBuilder
                .speak("すみません。問題が発生しました。")
                .getResponse();
        }
        // ユーザーが情報共有に同意したかどうかを確認します。
        const voiceConsentStatus = handlerInput.requestEnvelope.request.cause.result.status;

        if (voiceConsentStatus == 'ACCEPTED') {
           performBusinessLogic(...);
           return handlerInput.responseBuilder
              .speak("ありがとうございます。")
              .getResponse();
        }
        else {
           return handlerInput.responseBuilder
              .speak("リクエストに対応するには、この情報へのアクセス権限が必要です。Alexaアプリで権限を付与してください。")
              .askForPermissionsConsentCard([
                 "<permissionScope>",
                  "<別のpermissionScope>",
                  ...
               ])
              .getResponse();
        }

};

スキルに音声による同意確認を実装する手順

スキルに音声による同意確認を実装するには、次の手順に従います。

カスタムスキルを作成する
スキルを設定する
スキルコードで音声による同意確認を実装する
実装をテストする
スキルの認定を受ける。
音声による同意確認のメトリクスを確認する

ステップ1：カスタムスキルを作成する

カスタムスキルの作成方法の詳細については、カスタムスキルとはまたはカスタムスキルのビルド手順を参照してください。

ステップ2：スキルを設定する

スキルが音声による同意確認を使用できるようにするには、まず必要な権限を処理できるようにスキルを設定する必要があります。また、Skill Connectionsタスクのサポートを追加する必要もあります。

スキルに音声による同意確認を設定するには

Alexa開発者コンソールにサインインし、スキルに移動します。
ビルドタブをクリックします。
左側のツールをクリックし、アクセス権限をクリックします。
識別された発話者（アカウント所有者である場合とそうでない場合があります）の情報が必要な場合は、スキルのパーソナライズをオンにします。
この設定は、スキルで音声IDを使用するために必要です。
必要なユーザー情報のオプションをオンにします。たとえば、ユーザー名＞姓名、ユーザーの電話番号などです。

ステップ3：スキルコードで音声による同意確認を実装する

音声による同意確認を実装するために、スキルは次のことを行います。

ユーザー情報が必要になった時点で、Amazonが所有する音声同意確認スキルに制御を渡します。詳細については、音声による同意確認フローの開始方法を参照してください。
Amazonが所有する音声同意確認スキルから制御を受け取り、必要に応じて結果を処理します。詳細については、音声による同意確認フローの後に制御を再開する方法を参照してください。

これらの処理がワークフロー全体のどこに位置するかについては、音声による同意確認の標準ワークフローを参照してください。

ステップ4：実装をテストする

次の手順に従って、Echoデバイスを使った音声による同意確認フローのテストを実施します。

注： AlexaアプリとEchoデバイスは、スキルの作成時に使った開発者アカウントと同じAmazonアカウントに登録する必要があります。

実装をテストする

音声による同意確認をテストするには、まずAlexaアプリで音声IDをセットアップする必要があります。既に音声IDがある場合、このステップを省略できます。
1. Alexaアプリを開きます。
2. 下にあるその他を選択します。
3. 設定を選択してから、プロフィール＆家族を選択します。
4. 画面の指示に従ってプロフィールを追加します。
5. 画面の指示に従って音声IDを追加します。
開発者コンソールで、次のようにスキルのテストを有効にします。
1. Alexa開発者コンソールにサインインします。
2. スキルリストからスキルを選択します。
3. 上部のテストタブをクリックします。
4. 左上のヘッダーバーの下にあるスキルテストが有効になっているステージで、開発中を選択します。
Echoデバイスでスキルを開き、音声による同意確認の統合をトリガーするフローを進めます。音声による同意確認シナリオの例については、音声による同意確認の標準ワークフローを参照してください。

スキルが「姓名」など、よりリスクの高いアクセス権限を使用している場合、Alexaはスマートフォンにワンタイムパスワードを送信します。
注：ほかのユーザーと同様、Alexaのアクセス権限を求める質問に「許可します」と回答した場合、Alexaはアクセス権限を保存し、もう一度確認することはありません。

ステップ5：スキルの認定を受ける

スキルをビルドし、自身のアカウントでテストしたら、スキルの認定を申請できます。カスタムスキルの認定の詳細については、認定の要件を参照してください。

ステップ6：音声による同意確認のメトリクスを確認する

スキルの音声による同意確認のメトリクスを確認するには、開発者コンソールでレポートダッシュボードに移動します。音声による同意確認には、次のメトリクスを使用できます。

音声による同意確認を行ったユーザーの合計数
音声による同意確認イベント（音声による同意確認の呼び出しおよび完了）の合計数
音声による同意確認の完了率（許可されたリクエストと拒否されたリクエストの割合）
音声による同意確認の例外数

このページは役に立ちましたか？

フィードバックを送信

最終更新日: 2022 年 03 月 24 日

Alexaスキルで音声による同意確認を使用する

スキル権限の概要

前提条件

音声による同意確認の標準ワークフロー

ユーザーが情報共有に同意した場合

ユーザーが情報共有を拒否した場合

ユーザーが質問に答えない場合

音声による同意確認フローの開始方法

音声による同意確認フローの後に制御を再開する方法

スキルに音声による同意確認を実装する手順

ステップ1： カスタムスキルを作成する

ステップ2： スキルを設定する

ステップ3： スキルコードで音声による同意確認を実装する

ステップ4： 実装をテストする

ステップ5： スキルの認定を受ける

ステップ6： 音声による同意確認のメトリクスを確認する

関連トピック

このページは役に立ちましたか？

ステップ1：カスタムスキルを作成する

ステップ2：スキルを設定する

ステップ3：スキルコードで音声による同意確認を実装する

ステップ4：実装をテストする

ステップ5：スキルの認定を受ける

ステップ6：音声による同意確認のメトリクスを確認する