Alexaタイマーの概要



Alexaタイマーの概要

AlexaタイマーAPIを使うと、スキルにタイマー機能を追加できます。AlexaタイマーAPIは、REST APIのセットで構成されます。スキルでタイマーを作成するには、ユーザーの明示的な許可が必要です。また、そのユーザーがそのスキルで作成したタイマーのみを管理できます。詳しくはAlexaタイマーAPIリファレンスおよびAlexaタイマーのガイドラインを参照してください。

スキルにタイマーを含める

AlexaタイマーAPIを使うと、スキルからタイマーが直接設定されるため、ユーザーはスキルを終了せずにタイマーをセットできるようになります。これにより、スキルが中断されないユーザーエクスペリエンスを実現できます。

ユーザーの許可を取得する

スキルでタイマーを作成するには、まずユーザーの許可をとる必要があります。Alexaサービスは、スキルごとにタイマーを使用する権限を提供します。ユーザーがスキルにタイマーのアクセス権限を付与していない場合、スキルがユーザーにアクセス権限の付与方法を説明するようにしてください。あわせて、ユーザー同意をリクエストする権限カードをAlexaアプリに送信するようにしてください。

スキルがタイマーを作成し、タイマーの時間が来ると、Alexaはその時点でユーザーとAlexaがどのような対話をしていてもタイマーの処理を実行します。この動作は、ユーザーがこのタイマーを聞きたくない場合、対話の妨げになります。不要な割り込みをしないように、タイマーの作成には、次の2つの段階でユーザーの許可を得る必要があります。

  • タイマーの読み取り/書き込み全般に関するアクセス権限。スキルを有効にする際に確認を求めます。
  • タイマーによって得られる追加体験に対するユーザーの明示的な許可。明示的な許可は、スキルがユーザーに対して示すダイアログの一部として取得します。たとえばスキルのプロンプトで「30分のワークアウトを開始しますか?」とユーザーにたずねて許可を得ます。

タイマーワークフローの例

以下は、スキルユーザーがタイマーのセットに同意し、タイマーが鳴動し、ユーザーが「止めて」または「一時停止して」と言った場合の例です。

タイマー停止のワークフロー

  1. チキンの調理に今から5分間のタイマーを設定します。
  2. 割り込みがなければ、5分後にタイマーが鳴動します。
  3. タイマーにラベルがある場合は、鳴動に加えてAlexaが繰り返し「チキンのタイマーは終わりました」(ラベル名が「チキン」の場合)と言います。
  4. そして次のいずれかのアクションが発生するまで鳴動を続けます。

    • ユーザーが「アレクサ、止めて」または同様の発話をした場合。
    • 応答がないまま60分経過し、タイマーが鳴動を停止。

タイマー一時停止のワークフロー

  1. スキルが今から5分間のタイマーを設定します。
  2. 1分後に、ユーザーが「アレクサ、一時停止して」または同様の発話をするか、スキルが一時停止APIメソッドを呼び出します。
  3. スキルはタイマーを一時停止します。
  4. タイマーはユーザーが「アレクサ、再開して」と言うか、再開APIメソッドを呼び出すまで一時停止のままです。
  5. タイマーが再開すると、スキルは残りの4分間が経過した後に、タイマーの鳴動を開始します。
  6. タイマーはタイマー停止のワークフローで説明した方法で停止しない限り、1時間鳴動を続けます。

スキルにタイマーを追加する

次の手順に従って、既存または新規のAlexaカスタムスキルにAlexaタイマーを簡単に組み込むことができます。

  1. ユーザーが、タイマー作成の権限をリクエストできるようスキルをセットアップします。Amazon開発者コンソールで、スキルのビルドページを開き、下にスクロールして左下のアクセス権限を選択します。タイマーのスイッチをオンにします。SMAPIを使ってスキルを作成している場合、スキルマニフェストを直接編集して alexa::alerts:timers:skill:readwritepermissions.name配列に追加します。
  2. スキルのコードにタイマー機能を実装します。
  3. スキルがユーザーにタイマーの権限をリクエストするようにします。APIを使い、タイマーの読み込みと更新を行います。スキルがアクセスできるのは、そのスキルによって作成されたタイマーのみです。
  4. ユーザーは、タイマーが配信されたことを示すカードをAlexaアプリで受信します。

apiAccessTokenを使用したアクセス権限の管理

スキルがAlexaタイマーAPIを使用してタイマーを作成する場合、スキルはユーザーが明示的なアクセス権限を付与したセッション内IDを提供する必要があります。スキルが権限ポリシーに違反したとAlexaタイマーAPIが判断した場合、APIはタイマーへのアクセスを取り消します。スキルはセッション外トークンを使ってタイマーを作成することはできませんが、トークンを使ってタイマーの編集と削除はできます。

ユーザーがスキルを初めて起動したときなど、ユーザーが明示的にスキルに権限を付与していない場合は、Alexaアプリに権限カードを送信して、ユーザーの同意を得る必要があります。詳細については、ユーザー同意をリクエストする権限カードを参照してください。タイマーのスコープはalexa::alerts:timers:skill:readwriteです。

スキルに送信される各リクエストには、スキルに与えられた権限をカプセル化するAPIアクセストークン(apiAccessToken)が含まれています。スキルサービスは、APIを呼び出してタイマーを作成する際に使用するためにこのトークンを取得する必要があります。以下の例では、apiAccessTokenSystemオブジェクトに含まれ、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

詳細については、Alexaから送信されたリクエストを処理するを参照してください。