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

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

ユーザーに適切な権限を付与されたAlexaスキルはすべて、ユーザーのAlexaリストにアクセスできます。さらに、スキル開発者は、スキルイベントとリストイベントを直接統合することもできるようになりました。スキルは、リストAPIを呼び出さなくても、リストイベントが発生したときに通知を受けるようリストイベントにサブスクリプションを行うことで、リストが変更されたかどうかを確認できます。これらのイベントにアクセスすることで、さらに豊富な機能を持つスキルや外部アプリを開発できます。たとえば、サードパーティアプリはAlexaリストやリスト変更イベントへのアクセスを利用して、対応するリストイベントを受信したときにアプリのユーザーリストとユーザーのAlexaリストを同期させることができます。

Alexaリストをサードパーティアプリに保存されたリストと同期するには、ユーザーがAlexaのアカウントリンクを使用して、Alexaアカウントをサードパーティアプリのアカウントにリンクする必要があります。ユーザーがリストの共有を開始したり終了したりしたタイミングを知るには、ユーザーがスキルにリストへの権限を付与または取り消したタイミングを、アプリに通知する必要があります。リストイベントとスキルイベントを使用することで、アプリはこれらの情報を得ることができます。

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

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

カスタムスキルにリスト管理機能を持たせる場合、Alexaの買い物リストとやることリストにアクセスするの手順に従います。ただし、これらのリスト管理機能にはリストイベントが含まれません。スキルサービスでイベントを使用するには、リストスキルを作成する必要があります。詳細についてはリストスキルの作成手順を参照してください。

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

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

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

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

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

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

このため、イベントに対するアクションを実行する場合は、イベントのタイムスタンプを考慮してください。たとえば、ユーザーがリスト項目を追加し、その後削除すると、リスト項目の追加イベントと削除イベントの両方が発生します。この場合、スキルが追加イベントの前に削除イベントを受信しても、スキルがAlexaリストに項目を追加しないようにします。

イベントで使用されるapiEndpoint値

EUリージョンのユーザーの場合、イベントで受信するapiEndPointの値はhttps://api.eu.amazonalexa.comです。リストAPIを呼び出す場合、リージョンにかかわらず、すべてのユーザーに対してUSのエンドポイントhttps://api.amazonalexa.comを使用します。リストAPIにはEUエンドポイントがないためです。ただし、スキルメッセージAPIの場合、ユーザーのリージョンに応じて適切なエンドポイントを呼び出す必要があります。この値は、SkillEnabledまたはSkillAccountLinkedイベントで取得できます。

JSON形式のリストイベント

一般的なスキルイベントについては、Alexaのスキルイベントを参照してください。

リスト項目作成イベント

このイベントは、ユーザーがリストに新しい項目を作成したことを表します。スキルは、GetListItem APIを呼び出すことで、項目の情報を取得することができます。

{
  "version": "1.0",					// バージョン、 文字列
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"		// スキル id、 文字列
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",	// スキルの ユーザー id、 文字列
        "accessToken": "<access_token>",	// サードパーティー で ユーザー を 識別 するトークン
        "permissions": {
          "consentToken": "Atza|IgEB..."	// Lists API を 呼び出す トークン
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"	// Lists API を 呼び出す エンドポイント
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ItemsCreated",
    "requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9",	// 文字列
    "timestamp": "2017-09-15T01:46:14Z",	// タイムスタンプ, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "listId": "09d9d7df-05be-438c-veba-9d32968b4509",	// リスト id、 文字列
      "listItemIds": [
           "520a9f98-8e73-4fb8-veba-bfb6576cf623"		// 項目 id、 文字列
      ]

    }
  },
  "session": {
    "attributes": {}
  }
}

リスト項目更新イベント

このイベントは、ユーザーがユーザーリストの項目を更新したか、項目の状態が変更されたことを表します。

{
  "version": "1.0",					// バージョン、 文字列
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"		// スキル id、 文字列
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",	// スキルの ユーザー id、 文字列
        "accessToken": "<access_token>",	// サードパーティー で ユーザー を 識別 するトークン
        "permissions": {
          "consentToken": "Atza|IgEB..."	// Lists API を 呼び出す トークン
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"	// Lists API を 呼び出す エンドポイント
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ListUpdated",
    "requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9",	// 文字列
    "timestamp": "2017-09-15T01:46:14Z",	// タイムスタンプ, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "listId": "09d9d7df-05be-438c-veba-9d32968b4509",	// リスト id、 文字列
      "listItemIds": [
           "520a9f98-8e73-4fb8-veba-bfb6576cf623"		// 項目 id、 文字列
      ]

    }
  },
  "session": {
    "attributes": {}
  }
}

リスト項目削除イベント

このイベントは、ユーザーがユーザーリストの項目を削除したことを表します。

{
  "version": "1.0",					// バージョン、 文字列
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"		// スキル id、 文字列
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",	// スキルの ユーザー id、 文字列
        "accessToken": "<access_token>",	// サードパーティー で ユーザー を 識別 するトークン
        "permissions": {
          "consentToken": "Atza|IgEB..."	// Lists API を 呼び出す トークン
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"	// Lists API を 呼び出す エンドポイント
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ListDeleted",
    "requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9",	// 文字列
    "timestamp": "2017-09-15T01:46:14Z",	// タイムスタンプ, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "listId": "09d9d7df-05be-438c-veba-9d32968b4509",	// リスト id、 文字列
      "listItemIds": [
           "520a9f98-8e73-4fb8-veba-bfb6576cf623"		// 項目 id、 文字列
      ]
    }
  },
  "session": {
    "attributes": {}
  }
}

リスト作成イベント

このイベントは、ユーザーが新しいユーザーリストを作成したことを表します。GetListsMetadataスキルは、APIを呼び出すことで、このリストの情報を取得することができます。

{
  "version": "1.0",					// バージョン、 文字列
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"		// スキル id、 文字列
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",	// スキルの ユーザー id、 文字列
        "accessToken": "<access_token>",	// サードパーティー で ユーザー を 識別 するトークン
        "permissions": {
          "consentToken": "Atza|IgEB..."	// Lists API を 呼び出す トークン
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"	// Lists API を 呼び出す エンドポイント
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ListCreated",
    "requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9",	// 文字列
    "timestamp": "2017-09-15T01:46:14Z",	// タイムスタンプ, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "listId": "09d9d7df-05be-438c-veba-9d32968b4509"	// リスト id、 文字列
    }
  },
  "session": {
    "attributes": {}
  }
}

リスト更新イベント

このイベントは、ユーザーがユーザーリストを更新したことを表します。本来、このイベントはユーザーがリストの名前を変更したことを知らせるものです。ユーザーは、Alexaのやることリストと買い物リストの名前の変更はできません。

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions": { 
          "consentToken": "string"
        }
      },
      "apiEndpoint": "https://api.fe.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ListUpdated",
    "requestId": "string",
    "timestamp": "string",
    "body": {
      "listId" : "string"
    }
  }
}

リスト削除イベント

このイベントは、ユーザーがユーザーリストを削除したことを表します。ユーザーは、Alexaのやることリストと買い物リストは削除できません。

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "accessToken": "string",
        "permissions": { 
          "consentToken": "string"
        }
      },
      "apiEndpoint": "https://api.fe.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ItemsDeleted",
    "requestId": "string",
    "timestamp": "string",
    "body": {
      "listId" : "string",
      "listItemIds" : ["string", ...]
    }
  }
}

サンプルコード

イベントを処理するコードをスキルサービスに追加する方法については、Alexaリストイベントのデモを参照してください。