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



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

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

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

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

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

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

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

同様に、ユーザーがスキルに権限を付与した場合、consentTokenフィールドを含むpermissionsオブジェクトがスキルイベントとリストイベントの両方のユーザーオブジェクトに追加されます。権限が付与されない場合は追加されません。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.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ListUpdated",
    "requestId": "string",
    "timestamp": "string",
    "body": {
      "listId" : "string"
    }
  }
}

リスト削除イベント

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

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

よくある質問

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

関連トピック： リストスキルの作成と管理： FAQを参照してください。

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment