Alexaタイマーの概要
AlexaタイマーAPIを使用して、スキルにタイマーを追加できます。このページでは、タイマーのしくみについて簡単に説明します。タイマーの詳しい使用方法については、タイマーREST APIリファレンスおよびタイマーのベストプラクティスを参照してください。
スキルにタイマーを含める
AlexaタイマーAPIを使うと、スキルからタイマーが直接設定されるため、ユーザーはスキルを終了せずにタイマーを設定できるようになります。これにより、ユーザーはスキルの使用を中断することなく継続できるため、より優れたユーザーエクスペリエンスを実現できます。
ユーザーの許可を取得する
スキルでタイマーを作成するには、まず明示的にユーザーの許可をとる必要があります。Alexaサービスは、スキルごとにタイマーを使用する権限を提供します。ユーザーがスキルにタイマーのアクセス権限を付与していない場合、スキルがユーザーにアクセス権限の付与方法を説明するようにしてください。あわせて、ユーザー同意をリクエストする権限カードをAlexaアプリに送信するようにしてください。
スキルがタイマーを作成し、タイマーの時間が来ると、Alexaはその時点でユーザーとAlexaがどのような対話をしていてもタイマーの処理を実行します。この動作は、ユーザーがこのタイマーを聞きたくない場合、対話の妨げになる可能性があります。不要な割り込みをしないように、タイマーの作成には、次の2つの段階でユーザーの許可を得る必要があります。
- タイマーの読み取り／書き込み全般に関するアクセス権限。スキルを有効にする際にこの権限を求めます。
- タイマーによって得られる追加体験に対するユーザーの明示的な許可。明示的な許可は、スキルがユーザーに対して示すダイアログの一部として取得します。たとえばスキルのプロンプトで「30分のワークアウトを開始しますか？」とユーザーにたずねて許可を得ます。
タイマーワークフローの例
以下は、スキルユーザーがタイマーのセットに同意し、タイマーが鳴動し、ユーザーが「止めて」または「一時停止して」と言った場合の例です。
タイマー停止のワークフロー
- チキンの調理に今から5分間のタイマーを設定します。
- 割り込みがなければ、5分後にタイマーが鳴動します。
- タイマーにラベルがある場合は、鳴動に加えてAlexaが繰り返し「チキンタイマーが終了しました」（ラベル名が「チキン」の場合）と言います。
-
そして次のいずれかのアクションが発生するまで鳴動を続けます。
- ユーザーが「アレクサ、止めて」または同様の発話をした場合。
- 応答がないまま60分経過し、タイマーが鳴動を停止。
タイマー一時停止のワークフロー
- スキルが今から5分間のタイマーを設定します。
- 1分後に、ユーザーが「アレクサ、一時停止して」または同様の発話をするか、スキルが一時停止APIメソッドを呼び出します。
- スキルはタイマーを一時停止します。
- タイマーはユーザーが「アレクサ、再開して」と言うか、再開APIメソッドを呼び出すまで一時停止のままです。
- タイマーが再開すると、スキルは残りの4分間が経過した後に、タイマーの鳴動を開始します。
- タイマーはタイマー停止のワークフローで説明した方法で停止しない限り、1時間鳴動を続けます。
スキルにタイマーを追加する
次の手順に従って、既存または新規のAlexaカスタムスキルにAlexaタイマーを簡単に組み込むことができます。
- タイマーを作成するためのユーザー権限をリクエストできるよう、スキルを設定します。Amazon開発者コンソールで、スキルのビルドページを開き、下にスクロールして左下のアクセス権限を選択します。タイマーのスイッチをオンにします。SMAPIを使ってスキルを作成している場合、スキルマニフェストを直接編集して
alexa::alerts:timers:skill:readwriteをpermissions.name配列に追加します。 - スキルのコードにタイマー機能を実装します。
- スキルがユーザーにタイマーの権限をリクエストするようにします。APIを使い、タイマーの読み込みと更新を行います。スキルがアクセスできるのは、そのスキルによって作成されたタイマーのみです。
- ユーザーは、タイマーが配信されたことを示すカードをAlexaアプリで受信します。
apiAccessTokenを使用したアクセス権限の管理
スキルがAlexaタイマーAPIを使用してタイマーを作成する場合、スキルはユーザーが明示的なアクセス権限を付与したセッション内IDを提供する必要があります。スキルが権限ポリシーに違反したとAlexaタイマーAPIが判断した場合、APIはタイマーへのアクセスを取り消します。スキルはセッション外トークンを使ってタイマーを作成することはできませんが、トークンを使ってタイマーの編集と削除はできます。
ユーザーがスキルを初めて起動したときなど、ユーザーが明示的にスキルに権限を付与していない場合は、Alexaアプリに権限カードを送信して、ユーザーの同意を得る必要があります。詳細については、ユーザー同意をリクエストする権限カードを参照してください。タイマーのスコープはalexa::alerts:timers:skill:readwriteです。
スキルに送信される各リクエストには、スキルに与える権限をカプセル化するAPIアクセストークン（apiAccessToken）が含まれています。スキルサービスは、APIを呼び出してタイマーを作成する際に使用するためにこのトークンを取得する必要があります。以下の例では、apiAccessTokenはSystemオブジェクトに含まれ、Systemオブジェクトはcontextオブジェクトに含まれます。リクエストの本文全体については、リクエストの形式を参照してください。
{
"context": {
"System": {
"apiAccessToken": "AxThk...",
"apiEndpoint": "https://api.fe.amazonalexa.com",
"device": {
"deviceId": "string-identifying-the-device",
"supportedInterfaces": {}
},
"application": {
"applicationId": "string"
},
"user": {}
}
}
}
以下の例では、アクセストークンがAuthorizationヘッダーに含まれています（形式： Bearer ACCESS_TOKEN）。このACCESS_TOKENは、AlexaリクエストメッセージのapiAccessTokenフィールドの値です。
Authorization: Bearer AxThk...6fnLok
以下は、Node.jsでのアクセストークン取得の例です。
accessToken = this.event.context.System.apiAccessToken
apiAccessTokenを使用したアクセス権限の管理について詳しくは、Alexaから送信されたリクエストを処理するを参照してください。
関連トピック
- タイマーを作成する際のベストプラクティスについて詳しくは、Alexaタイマーのベストプラクティスを参照してください。
- 音声による権限付与を使用したタイマーの設定について詳しくは、音声によるタイマーの権限付与を設定するを参照してください。
- タイマーAPIの使用について詳しくは、タイマーREST APIリファレンスを参照してください。
最終更新日: 2022 年 11 月 14 日