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

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

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

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

関連トピック:リストイベント

スキルサービスでのイベントの使用

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

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

  • 適切な権限を付与することを促すプロンプトを出すよう、スキルをセットアップする必要があります。スキルマニフェストにリストイベントが含まれる場合、skill.jsonファイルにはpermissionsInfoオブジェクトが必要です。詳細については、スキル定義の更新を参照してください。

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

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

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

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

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

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

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

セッション外の対話

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

  1. ClientIdClientSecretを入力し、スキルメッセージAPIアクセストークンを取得します。これらのx id="locked2504" xid="lockTU_3cb55a36-df81-4c90-a678-403c9c9959a4" />とClientSecretの値を取得するには、Amazon開発者ポータルでスキルのエンドポイントタブを参照します。リクエストの形式は、スキルにメッセージを送信するようアプリケーションやサービスを設定するを参照してください。スキルをSMAPIで管理している場合でも、開発者ポータルでこれらの値を参照できます。スキルのリストに移動します。適切な権限を持ったスキルには、スキルIDおよびクライアントシークレットを表示するリンクが表示されます。このリンクをクリックすると、スキルID、クライアントID、クライアントシークレットがポップアップに表示されます。

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

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

スキルにイベントを配信する

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

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

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

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

JSON形式のスキルイベント

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

AccountLinkedイベント

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

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

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions": {
          "consentToken": "string"
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillAccountLinked",
    "requestId": "string" (alexa.skill.event.UUID),
    "body": {
      "accessToken": "string"
    },
    "timestamp": "string" (UTC: yyyy-mm-dd't'hh:mm:ss'z')
  }
}

SkillEnabledイベント

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

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string"
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillEnabled",
    "requestId": "string",
    "timestamp": "string"
  }
}

SkillDisabledイベント

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

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string"
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillDisabled",
    "requestId": "string",
    "timestamp": "string"
  }
}

SkillPermissionAcceptedイベント

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

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

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions":{
          "consentToken":"string"
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillPermissionAccepted",
    "requestId": "string",
    "timestamp": "string",
    "body": {
      "acceptedPermissions":  [{
          “scope”: "string"
      }],
    }
  }
}

SkillPermissionChangedイベント

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

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

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions":{
          "consentToken":"string"
        },
      "apiEndpoint": "https://api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.SkillPermissionChanged",
    "requestId": "string",
    "timestamp": "string",
    "body": {
      "acceptedPermissions":  [{
          “scope”: "string"
      }]
    }
  }
}