[Alexa] スキルからTo-doリストやShoppingリストを操作する

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 パーミッション

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)の４つの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