Alexaスキルのスキルイベント

---

• スキルサービスでイベントを使用するための前提条件
• イベントのアクセストークン、権限、同意トークン
  • イベント作成および公開のフィールド
  • セッション外の対話
• スキルへのイベントの配信
• スキルへのイベント着信の順序
• JSON形式のスキルイベント
  • アカウントリンクイベント
  • スキル有効化イベント
  • スキル無効化イベント
  • スキル権限付与イベント
  • スキル権限変更イベント

スキル開発者は、Alexaスキルイベントを直接統合することができるようになりました。これらのイベントにスキルでサブスクリプションを行うと、スキルはイベント発生時に通知を受け取ります。これらのイベントにアクセスすることで、さらに豊富な機能を持つスキルや外部アプリを開発できます。スキルイベントは、ユーザーがスキルを有効または無効にしたとき、サードパーティアカウントとスキルのリンクまたはリンク解除を行ったとき、スキルに権限を付与したとき、スキルに付与した権限を変更したときに生成されます。

カスタムスキルやスマートホームスキルなどすべてのスキルモデルは、スキルイベントをサポートします。

指定したユーザーデータにアクセスする権限は、スキルレベルで付与されます。またイベントに関しては権限の設定はありません。

スキルサービスでイベントを使用するための前提条件

スキルサービスでイベントを使用するには、Alexaスキル管理API（SMAPI）へのアクセスをセットアップする必要があります。方法については、SMAPIを使ってスキルにイベントを追加するを参照してください。SMAPIを使用する場合、ASK CLI（Alexa Skills Kitコマンドラインインターフェース）を使用してスキルを開発する必要があります。これは、SMAPIでサポートされる一部の機能がAmazon開発者ポータルではサポートされないためです。スキルイベント機能もそのうちの1つです。そのため、スキルイベントを使用するスキルをセットアップする場合、管理できるのはASK CLIのみとなります。Amazon開発者ポータルでは管理できません。

開発者の方は、スキルマニフェストがスキルでイベントを管理するための要件を満たすことを確認してください。

• ユーザーに対して適切な権限を付与することを促すプロンプトを出すよう、スキルをセットアップする必要があります。スキルで必要な場合は、スキルの適切なスコープを使用して、permissionsオブジェクトを追加します。詳細については、スキルマニフェストのスキーマを参照してください。

• スキルマニフェストには、イベントへのサブスクリプションを含むeventsオブジェクトが必要です。スキルマニフェストのスキーマを参照してください。

  スキルマニフェストでイベントのサブスクリプションを設定する方法についてのデモは、GitHubのalexa-cookbookリポジトリのDelete Persistent Attributes Demoをご覧ください。

• AWS Lambda関数のエンドポイントがAlexa Skills Kitトリガーを使用して設定されていることを確認します。これはAWSコンソールで行うことができます。詳細はこちらを参照してください。

スキルメッセージAPIを使ってセッション外の対話からユーザーの同意トークンを取得するには、セッション外の対話を参照してください。

指定したユーザーのスキルにメッセージリクエストを送信するには、スキルにメッセージリクエストを送信するを参照してください。

イベントのアクセストークン、権限、同意トークン

以下のイベントの多くにaccessTokenフィールドがありますが、ユーザーがAlexaアカウントを適切なサードパーティアプリにリンクしていなければaccessTokenは存在しません。

ただし、スキル開発者は、アクセストークンがアカウントリンクイベントで取得される場合以外には、アクセストークンに依存できません。スキルサービスは、アカウントリンクイベントでアクセストークンを受信したときに、AlexaユーザーIDとサードパーティユーザーIDとの関係を保持している必要があります。

同様に、ユーザーがスキルに権限を付与した場合、consentTokenフィールドを含むpermissionsオブジェクトがイベントのユーザーオブジェクトに追加されます。権限が付与されない場合は追加されません。consentTokenフィールドがnullの場合、permissionsオブジェクトは存在しません。

イベント作成および公開のフィールド

以下のすべてのスキルイベントに含まれるtimestamp、eventCreationTime、eventPublishingTimeフィールドは、UTC: YYYY-MM-DD'T'hh:mm:ss'Z'形式です。timestampフィールドは廃止されますので、eventCreationTimeを使用してください。 eventPublishingTimeは、リクエストがもともとの公開時刻から150秒以内に送信されたかどうかを検証するために使用します。

セッション外の対話

アプリは、ユーザーの音声リクエスト以外のスキルにアクセスする必要がある場合、以下のようにセッション外のアクセストークンをリクエストできます。

1. ClientIdとClientSecretを入力し、スキルメッセージAPIアクセストークンを取得します。これらのClientIdとClientSecretの値を取得するには、Amazon開発者ポータルでスキルのConfigurationタブを参照します。リクエストの形式については、スキルにメッセージを送信するようアプリケーションやサービスを設定するをご覧ください。スキルをSMAPIで管理している場合でも、開発者ポータルでこれらの値を参照できます。スキルのリストに移動します。スキルに権限を設定すれば、スキルIDおよびクライアントシークレットを表示のリンクが表示されます。このリンクをクリックすると、スキルID、クライアントID、クライアントシークレットがポップアップに表示されます。

2. アクセストークンを取得したら、アプリはスキルメッセージAPIアクセストークンとuserId値を使用してスキルメッセージAPIに非同期呼び出しを行います。この値はこれ以前のユーザー音声対話で取得されたものです。スキルメッセージAPIは、ユーザー同意トークンを使用してスキルをコールバックします。

関連トピック： スキルメッセージAPI

スキルへのイベントの配信

Alexaは、スキルサービスが確認応答を送信しなかった場合、最大1時間イベントの再配信を試行します。スキルサービスがイベントを受信して、確認応答を送信した場合、スキルサービスは受け取ったイベントを適切に処理、管理する必要があります。どちらの場合も、スキルサービスは過去のイベントをAlexaから後で取得することはできません。

スキルへのイベント着信の順序

スキルイベントはスキルに送信されますが、これらのイベントをスキルが受信する順序が送信の順序と同じとは限りません。

そのため、イベントの結果としてスキルが実行するアクションでは、イベントのeventCreationTimeに注意する必要があります。たとえば、スキルが有効にされた後無効にされると、有効化イベントと無効化イベントの両方が発生します。スキルが有効化イベントの前に無効化イベントを受信した場合でも、スキルサービスがスキルが有効になっているとみなして動作しないようにします。

JSON形式のスキルイベント

以下のセクションでは、各スキルイベントのJSON形式について説明します。前のセクションで述べたケース以外では、accessTokenフィールドとpermissionsオブジェクトは存在しません。ケースに応じて、イベントにはリージョンに適したapiEndpoint値が含まれます。

アカウントリンクイベント

このイベントは、ユーザーがサードパーティアプリケーションのアカウントをAlexaアプリにリンクしたことを表します。このイベントは、セッション外（非音声）のユーザー対話をサポートするアプリケーションに便利です。内部ユーザーがAlexaユーザーに関連付けられたときにこのアプリケーションに通知します。このイベントは、ユーザーのAlexaリストとアプリケーションのリストを同期する多くのアプリケーションで必須です。

アカウントリンクプロセス中に、Alexaアプリはユーザーをスキルのウェブサイトに誘導し、ユーザーはここでログインします。ユーザーがログインすると、スキルはAlexaにアクセストークンと同意トークンを提供します。イベントにも同じアクセストークンと同意トークンが含まれます。

スキル有効化イベント

このイベントは、ユーザーがスキルを有効にしたときに送信されます。

スキル無効化イベント

このイベントは、ユーザーがスキルを無効にしたときに送信されます。スキルが無効にされると、権限はそれにともない暗黙的に取り消されますが、スキル権限変更イベントは送信されません。スキルサービスはこのスキル無効化イベントを処理する必要があります。SkillDisabledイベントにはuser_idのみが含まれ、アクセストークンは含まれません。これは、ユーザーがスキルを無効にすると、Amazonシステムからアクセストークンが削除されるためです。

userInformationPersistenceStatusは、独自の永続ストレージに保存されたこのユーザーのデータを削除しても安全かどうかを示します。

• PERSISTED： ユーザーがスキルを再度有効にする場合に同じuserIdを使用するために、データを消去しません。
• NOT_PERSISTED: ユーザーがスキルを再度有効にした場合、新しいuserIdが取得されます。そのため、userIdに伴って保存されたデータを消去しても安全です。

たとえば、スキルが消費型アイテムを提供する場合、userInformationPersistenceStatusはPERSISTEDです。この場合、userIdに関連付けられた消費型商品のインベントリーは維持されます。

スキル権限付与イベント

このイベントはユーザーが初めて権限を承認したか、すべての権限を取り消した後に権限を付与した場合に送信されます。スキルの権限を変更したり、付与したりするイベントの場合、直近で承認された権限がペイロードに常に含まれます。

ユーザーがAlexaアカウントを適切なサードパーティアプリにリンクした場合、accessTokenフィールドが存在します。

スキル権限変更イベント

このイベントは、ユーザーがスキルに追加の権限を付与したか、スキルの既存の権限を取り消した場合に送信されます。スキルの権限を変更したり、付与したりするイベントの場合、直近で承認された権限がペイロードに常に含まれます。

ユーザーがAlexaアカウントを適切なサードパーティアプリにリンクした場合、accessTokenフィールドが存在します。

---

---

最終更新日: 2024 年 07 月 01 日