この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
1 はじめに
Amazon Alexa(以下、Alexa)には、ショッピングや予定リストを管理する機能があります。
リストは、非常に柔軟に追加することが可能で、例えば、"Alexa, create a new to-do."とか、"Alexa, I need a bread."などと話しかけるだけで簡単に追加できます。
正確には、分からないのですが、明確にリストの種類を示さなくても、(名詞)だと、Shopping、(動詞)だと、To-doに入るように見えます。
なお、EchoやEcho dotデバイスからは、追加することしかできません。一覧を見たり、編集したりするには、Alexa Appが必要です。
利用例としては、自宅で音声により、気が付いた時に、必要な物をショッピングリストに追加しておき、買い物に出かけた際に、Alexaアプリでチェックするようなイメージでしょうか。
Shopping
To-do
iPhone
この2つのリストですが、パーミッションを設定することで、スキルから操作が可能になります。今回は、この機能について確認して見たいと思います。
2 パーミッション
Amazon開発者コンソールでスキルを作成する際に、ConfigurationのPermitionsでLists Read及び、List Writeのどちらか(若しくは、両方)にチェックすると、リストの読み書きに関する権限を要求することができます。
このパーミッションが設定されたスキルでは、ユーザーが許可を与えた時点で、リストにアクセスできるようになります。
ユーザーが許可を与えると、Alexaからのリクエストで、context.System.user.permissions.consentTokenにアクセストークンが付与されます。
リストへのアクセスには、このトークンが必要です。
var consentToken = this.event.context.System.user.permissions.consentToken
"context": {
"System": {
"application": {
"applicationId": "string"
},
"user": {
"userId": "amzn1.ask.account.<userId_value>",
"permissions": {
"consentToken": "Atza|MQEWY...6fnLok"
},
"accessToken": "string"
},
"device": {
"deviceId": "string",
"supportedInterfaces": {
"AudioPlayer": {}
}
},
"apiEndpoint": "string"
},
3 RestAPI
Alexaのリストは、下記のエンドポイントでアクセスできます。
Endpoint: https://api.amazonalexa.com/
API | Method | URI Endpoint |
---|---|---|
Get lists metadata | GET | v2/householdlists/ |
Get a list | GET | v2/householdlists/{listId}/{status} |
Get a list item | GET | v2/householdlists/{listId}/items/{itemId} |
Update a list item | PUT | v2/householdlists/{listId}/items/{itemId} |
Create a new list item | POST | v2/householdlists/{listId}/items |
Delete a list item | DELETE | v2/householdlists/{listId}/items/{itemId} |
(1) Get lists metadata
リストの一覧取得です。
Get lists metadataでは、まずは、To-do及び、Shoppingリストを取得するためのURLを取得します。
GET: v2/householdlists/
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
上記のAPIで、shopping(active)、shopping(completed)、To-do(active)、To-do(completed)の4つのURLが取得できます。
{
"lists": [
{
"listId": "IT1BQSU5(略)HX0lURU0=",
"name": "Alexa shopping list",
"state": "active",
"statusMap": [
{
"href": "/v2/householdlists/IT1BQSU5(略)HX0lURU0=/active",
"status": "active"
},
{
"href": "/v2/householdlists/IT1BQSU5(略)HX0lURU0=/completed",
"status": "completed"
}
],
"version": 1
},
{
"listId": "FQ1NJTllOS(略)lVVRBU0s=",
"name": "Alexa to-do list",
"state": "active",
"statusMap": [
{
"href": "/v2/householdlists/FQ1NJTllOS(略)lVBLVRBU0s=/active",
"status": "active"
},
{
"href": "/v2/householdlists/FQ1NJTllOS(略)lVBLVRBU0s=/completed",
"status": "completed"
}
],
"version": 1
}
]
}
そして、上記で得たURLを使用して、Shopping(active)及びTo-do(active)を取得した例です。Alexa アプリで見たものと同じであることが分かります。
Shopping List
{
"items": [
{
"createdTime": "Mon Aug 14 19:32:23 UTC 2017",
"href": "/v2/householdlists/YW16bjEuYWNjb3V(略)2eece1",
"id": "55c486bc-a5f4-3705-a5d7-5728c12eece1",
"status": "active",
"updatedTime": "Mon Aug 14 19:32:23 UTC 2017",
"value": "shampoo",
"version": 1
},
{
"createdTime": "Mon Aug 14 19:32:07 UTC 2017",
"href": "/v2/householdlists/YW16bjEuYWNjb3V(略)e848667",
"id": "58496aa8-4e96-5bca-92ab-ecb88e848667",
"status": "active",
"updatedTime": "Mon Aug 14 19:32:07 UTC 2017",
"value": "butter",
"version": 1
},
{
"createdTime": "Mon Aug 14 19:31:52 UTC 2017",
"href": "/v2/householdlists/YW16bjEuYWNjb3V(略)14ec9e4",
"id": "a6167bf7-c8b7-8f4f-437f-5be5514ec9e4",
"status": "active",
"updatedTime": "Mon Aug 14 19:31:52 UTC 2017",
"value": "Plain bread",
"version": 1
}
],
"links": null,
"listId": "IT1BQSU5(略)HX0lURU0=",
"name": "Alexa shopping list",
"state": "active",
"version": 1
}
To-do list
{
"items": [
{
"createdTime": "Mon Aug 14 19:32:59 UTC 2017",
"href": "/v2/householdlists/YW16bjEu(略)f47c0687264",
"id": "960f10d8-db70-05e2-6925-7f47c0687264",
"status": "active",
"updatedTime": "Mon Aug 14 19:33:26 UTC 2017",
"value": "I go to the movies with Mary",
"version": 3
},
{
"createdTime": "Mon Aug 14 19:30:44 UTC 2017",
"href": "/v2/householdlists/YW16bjEu(略)36c06ad",
"id": "562e4d86-f59f-333e-833a-290ce36c06ad",
"status": "active",
"updatedTime": "Mon Aug 14 19:30:44 UTC 2017",
"value": "go to the gym",
"version": 1
}
],
"links": null,
"listId": "FQ1NJTllOS(略)lVVRBU0s=",
"name": "Alexa to-do list",
"state": "active",
"version": 1
}
(2) Get a list / Get a list item
個々のリストやアイテムを取得します。 listIdや、ItemIdは、GetListsMetadataで取得したものを使用します。
GET: v2/householdlists/{listId}/{status}
where {listId} is customer's list id and {status} is "active" or "completed"
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
GET: v2/householdlists/{listId}/items/{itemId}
where {listId} is customer's list id and {itemId} is the item id
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
(3) Update a list item
アイテムを更新します。
PUT: v2/householdlists/{listId}/items/{itemId}
where {listId} is customer's list id and {itemId} is the item id
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
{
"id": // item id (String)
"version": // item version when it was read (Positive integer)
"value": // updated item value (String, limit is 256 characters)
"status": // item status (Enum: "active" or "completed")
}
(4) Create a new list item
新しくアイテムを追加します。
POST: v2/householdlists/{listId}/items
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
{
"value": // new item value (String, limit is 256 characters)
"status": // item status (Enum: "active" or "completed")
}
(5) Delete a list item
アイテムを削除します。
DELETE: v2/householdlists/{listId}/items/{itemId}
Authorization: Bearer auth_token_for_customer
Content-Type: application/json
4 パーミッションの要求
ユーザーの許可が得られていない場合、Alexaアプリにカードを表示して、ユーザーに許可を促す必要があります。 Alexa SDK for nodejsを使用している場合、下記のレスポンスでRead + Writeを催促するカードが表示されます。
const READ_LIST_PERMISSION = "read::alexa:household:list";
const WRITE_LIST_PERMISSION = "write::alexa:household:list";
const PERMISSIONS = [READ_LIST_PERMISSION, WRITE_LIST_PERMISSION];
const message = 'Please enable Lists permissions in the Amazon Alexa app.';
this.emit(":tellWithPermissionCard", message, PERMISSIONS);
"card": {
"type": "AskForPermissionsConsent",
"permissions": [
"read::alexa:household:list",
"write::alexa:household:list"
]
}
}
Alexaアプリでは、下記のように表示されています。
5 最後に
Alexaのリストは、使い慣れると非常に便利かも知れません。そして、スキルを作成することで、リストを更に強化できるかも知れません。
例えば、定型業務をTo-doリストに追加するスキルとか・・・
googleカレンダーからイベントをリストに追加するとか・・・
6 参考リンク
Access the Alexa Shopping and To-Do Lists
Integrate Your Skills with Alexa Shopping and To-Do Lists
GitHub alexa/alexa-cookbook