音声によるタイマーの権限付与を設定する

音声によるタイマーの権限付与を設定する

音声によるタイマーの権限付与をスキルに設定すると、ユーザーは音声操作を通じてスキルにタイマーの権限を付与できます。ユーザーは「はい」と言うのみで、Alexaアプリを開く必要がなくなり、スキルをより便利に使えるようになります。

しくみ

  1. スキルがアクセス権限リクエストを開始します。
  2. Alexaは、特定のタイマーを作成する権限を付与するかどうかをユーザーに尋ねます。
  3. ユーザーがアクセス権限リクエストに応答します。
    • ユーザーがアクセス権限を付与した場合、スキルはタイマーを作成できます。Alexaアプリに権限リクエストのカードを送信する必要はありません。
    • ユーザーがアクセス権限を付与しなかった場合、スキルはタイマーを作成できません。ユーザーがタイマー作成権限を付与しない場合、スキルはフォールバックワークフローを提供する必要があります。

音声による権限付与の標準ワークフロー

タイマーをセットするかどうかの最初のプロンプトは、スキルが出します。このタイミングは、スキル側で決めることができます。

ユーザーが音声でタイマーの権限を付与する

この例では、仮想のスキル「クッキングタイム」はサードパーティの料理アプリにリンクしています。スキルが出力する応答の一部はスキル、一部はAlexaによって制御されています。

Alexa (スキルの応答) クッキングタイムへようこそ。料理のお手伝いをするために、このスキルはAlexaのタイマー機能を使用する必要があります。

Alexa(Alexaが制御) クッキングタイムに、タイマーの更新を許可しますか? 「はい」または「いいえ」と言ってください。

ユーザー: はい。

ユーザーが最初に同意したタイマーの権限付与を拒否する

ユーザーが最初にタイマーの権限付与に同意しても、後で拒否する場合があります。

スキルでは、最初のプロンプトを出す以外で、Alexaとユーザーの権限付与に関する対話を制御することはできません。

Alexa (スキルの応答) クッキングタイムへようこそ。料理のお手伝いをするために、このスキルではAlexaのタイマー機能へのアクセス権限が必要となります。

Alexa(Alexaが制御) クッキングタイムに、タイマーの更新を許可しますか? 「はい」または「いいえ」と言ってください。

ユーザー: いいえ。

ユーザーの応答が不明瞭

Alexaのタイマー権限付与リクエストに対してユーザーの応答が不明瞭だった場合、Alexaは質問を言い換えて再プロンプトします。再プロンプトの後、ユーザーが権限付与に同意したか拒否したかに応じて、その時点から対応するワークフローを継続します。

Alexa (スキルの応答) クッキングタイムへようこそ。料理のお手伝いをするために、このスキルはAlexaのタイマー機能を使用する必要があります。

Alexa(Alexaが制御) クッキングタイムに、タイマーの更新を許可しますか? 「はい」または「いいえ」と言ってください。

ユーザー:<不明瞭な応答>

Alexa(Alexaが制御) クッキングタイムに、タイマーの更新を許可しますか? 「はい」または「いいえ」と言ってください。

標準のプロンプト

スキルは音声によるタイマー権限付与ワークフローを開始し、ユーザーへの最初のプロンプトを制御します。Alexaは音声による権限付与ワークフローの次のプロンプトを制御します。このプロンプトにより、全スキルで一貫したエクスペリエンスを提供できます。参考のため、各プロンプトにタグを付けています。スキルは続けてAcceptConsentTimersプロンプトを出し、タイマーの内容、日時、目的を復唱します。応答のこの部分はスキルが制御します。

AskForConsentTimersAlexa(Alexaが制御) クッキングタイムに、タイマーの更新を許可しますか? 「はい」または「いいえ」と言ってください。

AskForConsentRetryTimersAlexa(Alexaが制御) クッキングタイムに、タイマーの更新を許可しますか? 「はい」または「いいえ」と言ってください。

Connections.SendRequestディレクティブを送信する

スキルからのタイマー設定の要求にユーザーが肯定的に応答すると、次に示すように、スキルサービスコードからConnections.SendRequestディレクティブを送信できます。permissionScopeの値は、タイマーのスコープ(alexa::alerts:timers:skill:readwrite)になります。

このディレクティブのtokenフィールドはAlexaでは使用されませんが、処理結果のConnections.Responseリクエストはtoken値を返します。このトークンは、スキルにとって意味のある形式で指定できます。不要な場合は空の文字列を使用できます。

consentLevelパラメーターは、同意を求める対象となるユーザーの粒度(レベル)です。有効な値はACCOUNTPERSONです。

  • ACCOUNTは、Alexa搭載デバイスが登録されているAmazonアカウントの所有者です。
  • PERSONは、識別されたユーザーです。識別されたユーザーの詳細については、Alexaスキルのパーソナライズを参照してください。
{
   "type": "Connections.SendRequest",
   "name": "AskFor",
   "payload": {
      "@type": "AskForPermissionsConsentRequest",
      "@version": "2",
      "permissionScopes": [
        {
          "permissionScope": "alexa::alerts:timers:skill:readwrite",
          "consentLevel": "ACCOUNT"
        }
      ]
   },
   "token": ""
}

このディレクティブを受け取ると、Alexaは、タイマーに必要なスコープのアクセス権限を付与するようユーザーに求めます。この処理結果はConnections.Responseリクエストでスキルに送信されます。body.statusの値は次のいずれかになります。

  • ACCEPTED - ユーザーが最後または前回のリクエストに応じて権限を付与しました。
  • DENIED - ユーザーが権限付与を拒否しました。
  • NOT_ANSWERED - ユーザーが権限付与のリクエストに応答しなかったか、ユーザーの応答が理解できませんでした。この場合、Alexaはユーザーに再度応答を求めます。
{
   "type": "Connections.Response",
   "requestId": "string",
   "timestamp": "string",
   "locale": "string",
   "name": "AskFor",
   "status": {
      "code": "string",
      "message": "string"
   },
   "token": "string",
   "payload": {
      "permissionScopes" : [
       {
         "permissionScope" : "alexa::alerts:timers:skill:readwrite",
         "consentLevel": "ACCOUNT"
       },
      "status" : <ステータスのenum> // ACCEPTEDDENIEDNOT_ANSWERED
      ]
   }
}

この例からわかるように、スキル開発時に変更できないAlexaの標準プロンプトが含まれます。これらのプロンプトは音声による権限付与の標準ワークフローに含まれているため、コーディングする必要はありません。

音声による権限付与リクエストのコードサンプル

以下は、アマゾン ウェブ サービス(AWS)のLambda関数にコードを追加して音声による権限付与リクエストのConnections.SendRequestディレクティブを送信する方法の例です。tokenフィールドを使用して、状態を追跡できます。tokenフィールドに指定した値は、Alexaへのユーザーのリクエストに表示されます。たとえば、tokenフィールドを使用してuserId値を格納できます。tokenを空の文字列に設定することもできます。

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

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

return handlerInput.responseBuilder
	.addDirective({
		type: "Connections.SendRequest",
		name: "AskFor",
		payload: {
			"@type": "AskForPermissionsConsentRequest",
			"@version": "2",
			"permissionScopes": [
			  {
			    "permissionScope": "alexa::alerts:timers:skill:readwrite",
			    "consentLevel": "ACCOUNT" 
			  } 
			]
		},
		token: "<文字列>"
	})
	.getResponse();

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

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

this.handler.response = {
	'version': '1.0',
	'response': {
		'directives': [{
			'type': 'Connections.SendRequest',
			'name': 'AskFor',
			'payload': {
			   '@type': 'AskForPermissionsConsentRequest',
			   '@version': '2',
			   'permissionScopes': [
			    {
			      'permissionScope': 'alexa::alerts:timers:skill:readwrite',
			      'consentLevel': 'ACCOUNT' 
			    } 
			   ]
			},
			'token': '<文字列>'
		}],
		'shouldEndSession': true
	}
};
this.emit(':responseReady');

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

音声による権限付与リクエストのConnections.SendRequestディレクティブのJSON構文です。この場合、nameRequestです。

{
  "directives": [
    {
      "type": "Connections.SendRequest",
      "name": "AskFor",
      "payload": {
        "@type": "AskForPermissionsConsentRequest",
        "@version": "2",
        "permissionScopes": [
          {
            "permissionScope": "alexa::alerts:timers:skill:readwrite",
            "consentLevel": "ACCOUNT"
          } 
        ]
      },
      "token": "<文字列>"
    }
  ]
}