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

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

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

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

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

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

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

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

同様に、ユーザーがスキルに権限を付与した場合、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のスキルイベントを参照してください。

ListItemsCreatedイベント

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

{
  "version": "1.0",					// Version, String
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"		// Skill id, String
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",	// Skill user id, String
        "accessToken": "<access_token>",	// Token to identify user in 3P
        "permissions": {
          "consentToken": "Atza|IgEB..."	// Token to call Lists API
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"	// Endpoint to call Lists API
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ItemsCreated",
    "requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9",	// String
    "timestamp": "2017-09-15T01:46:14Z",	// Timestamp, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "listId": "09d9d7df-05be-438c-veba-9d32968b4509",	// List id, String
      "listItemIds": [
           "520a9f98-8e73-4fb8-veba-bfb6576cf623"		// Item ids, String
      ]

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

ListItemsUpdatedイベント

このイベントはリストの項目が更新されたことを表します。項目のステータスが変更されたか、項目の値が更新された場合に送信されます。

{
  "version": "1.0",					// Version, String
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"		// Skill id, String
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",	// Skill user id, String
        "accessToken": "<access_token>",	// Token to identify user in 3P
        "permissions": {
          "consentToken": "Atza|IgEB..."	// Token to call Lists API
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"	// Endpoint to call Lists API
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ListUpdated",
    "requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9",	// String
    "timestamp": "2017-09-15T01:46:14Z",	// Timestamp, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "listId": "09d9d7df-05be-438c-veba-9d32968b4509",	// List id, String
      "listItemIds": [
           "520a9f98-8e73-4fb8-veba-bfb6576cf623"		// Item ids, String
      ]

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

ListItemsDeletedイベント

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

{
  "version": "1.0",					// Version, String
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"		// Skill id, String
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",	// Skill user id, String
        "accessToken": "<access_token>",	// Token to identify user in 3P
        "permissions": {
          "consentToken": "Atza|IgEB..."	// Token to call Lists API
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"	// Endpoint to call Lists API
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ListDeleted",
    "requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9",	// String
    "timestamp": "2017-09-15T01:46:14Z",	// Timestamp, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "listId": "09d9d7df-05be-438c-veba-9d32968b4509",	// List id, String
      "listItemIds": [
           "520a9f98-8e73-4fb8-veba-bfb6576cf623"		// Item ids, String
      ]
    }
  },
  "session": {
    "attributes": {}
  }
}

ListCreatedイベント

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

{
  "version": "1.0",					// Version, String
  "context": {
    "System": {
      "application": {
        "applicationId": "<skill_id>"		// Skill id, String
      },
      "user": {
        "userId": "amzn1.ask.account.VEBA...",	// Skill user id, String
        "accessToken": "<access_token>",	// Token to identify user in 3P
        "permissions": {
          "consentToken": "Atza|IgEB..."	// Token to call Lists API
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com"	// Endpoint to call Lists API
    }
  },
  "request": {
    "type": "AlexaHouseholdListEvent.ListCreated",
    "requestId": "913e4588-62f9-4d5b-b7ba-c0d3c1210ce9",	// String
    "timestamp": "2017-09-15T01:46:14Z",	// Timestamp, YYYY-MM-DD'T'hh:mm:ss'Z'
    "body": {
      "listId": "09d9d7df-05be-438c-veba-9d32968b4509"	// List id, String
    }
  },
  "session": {
    "attributes": {}
  }
}

ListUpdatedイベント

このイベントはリストが更新されたことを表します。本来、このイベントはユーザーがリストの名前を変更したことを知らせるものです。ユーザーは、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.ListUpdated",
    "requestId": "string",
    "timestamp": "string",
    "body": {
      "listId" : "string"
    }
  }
}

ListDeletedイベント

このイベントは、リストが削除されたことを表します。ユーザーは、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