Alexa List API を使用してリストを操作する

はじめに

Alexaアプリでは、簡単なアイテムを管理できるリスト機能があります。デフォルトでは、「買い物」と「やること」が作成されています。
Alexaアプリ上やビルトインスキルでリストおよびアイテムの追加や削除・更新ができます。さらに、List APIを使って操作することも可能になっています。

今回は、カスタムスキル上からリストを操作してみようと思います。

事前準備

AlexaのAPIをコールするためにask-sdk for nodejs v2には、ServiceClientFactoryというサービスクライアントがあります。 これを使うことで、ApiAccessToken・ApiEndpointを意識せずにAPIを使用できます。

ServiceClientFactoryを使用するためには、.withApiClient()にAlexa.DefaultApiClient()を設定します。

    const skillBuilder = Alexa.SkillBuilders.custom();
    handlers.forEach( handler => {
        skillBuilder.addRequestHandlers(<Alexa.RequestHandler>handler);
    });
    skillBuilder.withApiClient(new Alexa.DefaultApiClient());
    const skill = skillBuilder.create();
    return skill.invoke(event);

またハンドラー内で下記を使用します。

    const listManager = h.serviceClientFactory.getListManagementServiceClient();

これで準備完了です、使っていきましょう。

使ってみる

getListsMetadata()

getListsMetadataは、リストを全て取得します。

    let lists = await listManager.getListsMetadata();

{
    "lists": [
        {
            "listId": "YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVNIT1BQSU5HX0lURU0=",
            "name": "Alexa shopping list",
            "state": "active",
            "statusMap": [
                {
                    "href": "/v2/householdlists/YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVNIT1BQSU5HX0lURU0=/active",
                    "status": "active"
                },
                {
                    "href": "/v2/householdlists/YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVNIT1BQSU5HX0lURU0=/completed",
                    "status": "completed"
                }
            ],
            "version": 1
        },
        {
            "listId": "YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVRBU0s=",
            "name": "Alexa to-do list",
            "state": "active",
            "statusMap": [
                {
                    "href": "/v2/householdlists/YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVRBU0s=/active",
                    "status": "active"
                },
                {
                    "href": "/v2/householdlists/YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVRBU0s=/completed",
                    "status": "completed"
                }
            ],
            "version": 1
        }
    ]
}

取得したlistIdを使い、リスト情報の詳細情報を取得してみます。

getList(listId, status)

getListは、パラメータで指定されたlistIdのリストの詳細情報を取得します。
アレクサアプリで買い物のリストにEcho Showを追加してみました。 これでリスト情報を取得するとEcho Showが存在しているはずです。

    let getList = await listManager.getList('YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVNIT1BQSU5HX0lURU0=','active');

{
    "items": [
        {
            "createdTime": "Mon Oct 01 02:36:40 UTC 2018",
            "href": "/v2/householdlists/YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVNIT1BQSU5HX0lURU0=/items/5a01044a-9075-49b5-a6a6-69780d6e3540",
            "id": "5a01044a-9075-49b5-a6a6-69780d6e3540",
            "status": "active",
            "updatedTime": "Mon Oct 01 02:36:40 UTC 2018",
            "value": "Echo Show",
            "version": 1
        }
    ],
    "links": null,
    "listId": "YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVNIT1BQSU5HX0lURU0=",
    "name": "Alexa shopping list",
    "state": "active",
    "version": 1
}

getListItem(listId, itemId)

getListItemは、リストに登録されているアイテム情報を取得します。 先ほど追加した、Echo Showを確認します。

    let getListItem = await listManager.getListItem('YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVNIT1BQSU5HX0lURU0=','5a01044a-9075-49b5-a6a6-69780d6e3540');

{
    "createdTime": "Mon Oct 01 02:36:40 UTC 2018",
    "href": "/v2/householdlists/YW16bjEuYWNjb3VudC5BR1lQVUdMSU9VU05RN0Y2SE1QWkNaV1hPWE9BLVNIT1BQSU5HX0lURU0=/items/5a01044a-9075-49b5-a6a6-69780d6e3540",
    "id": "5a01044a-9075-49b5-a6a6-69780d6e3540",
    "status": "active",
    "updatedTime": "Mon Oct 01 02:36:40 UTC 2018",
    "value": "Echo Show",
    "version": 1
}

createList(createListRequest)

リストを新規作成します。

    let createListRequest: services.listManagement.CreateListRequest = {
        'name': 'createListTest',
        'state': 'active'
    };
    let createList = await listManager.createList(createListRequest);

{
    "listId": "5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf",
    "name": "createListTest",
    "state": "active",
    "statusMap": [
        {
            "href": "/v2/householdlists/5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf/active",
            "status": "active"
        },
        {
            "href": "/v2/householdlists/5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf/completed",
            "status": "completed"
        }
    ],
    "version": 1
}

createListItem(listId, createListItemRequest)

指定されたリストにアイテムを新規作成します。

    let createListItemRequest: services.listManagement.CreateListItemRequest = {
        'value': 'Echo Spot',
        'status': 'active'
    }
    let createListItem = await listManager.createListItem('5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf', createListItemRequest);          

{
    createdTime: 'Thu Oct 04 03:51:27 UTC 2018',
    href: '/v2/householdlists/5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf/items/99af7291-f307-47b2-816e-a8b1baf33dd0',
    id: '99af7291-f307-47b2-816e-a8b1baf33dd0',
    status: 'active',
    updatedTime: 'Thu Oct 04 03:51:27 UTC 2018',
    value: 'Echo Spot',
    version: 1
}

updateList(listId, updateListRequest)

既存のリストを更新します。先ほど作成したcreateListTestを更新してみましょう。

    let updateListRequest: services.listManagement.UpdateListRequest = {
        'name': 'updateListTest',
        'state': 'active',
        'version': 1
    };
    let updateList = await listManager.updateList('5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf', updateListRequest);

{
    "listId": "5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf",
    "name": "updateListTest",
    "state": "active",
    "statusMap": [
        {
            "href": "/v2/householdlists/5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf/active",
            "status": "active"
        },
        {
            "href": "/v2/householdlists/5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf/completed",
            "status": "completed"
        }
    ],
    "version": 1
}

updateListItem(listId, itemId, updateListItemRequest)

指定したリスト内のアイテムを更新します。

    let updateListItemRequest: services.listManagement.UpdateListItemRequest = {
        'value': 'Echo',
        'status': 'active',
        'version': 1
    };
    let updateListItem = await listManager.updateListItem('5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf', '99af7291-f307-47b2-816e-a8b1baf33dd0', updateListItemRequest);

{
    "createdTime": "Thu Oct 04 03:51:27 UTC 2018",
    "href": "/v2/householdlists/5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf/items/99af7291-f307-47b2-816e-a8b1baf33dd0",
    "id": "99af7291-f307-47b2-816e-a8b1baf33dd0",
    "status": "active",
    "updatedTime": "Thu Oct 04 04:00:50 UTC 2018",
    "value": "Echo",
    "version": 1
}

deleteList(listId)

listIdで指定したリストを削除します。

    let deleteList = await listManager.deleteList('5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf');

deleteListItem(listId, itemId)

指定したアイテムをリストから削除します。

    let deleteListItem = await listManager.deleteListItem('5f379a35-bf1c-4cc0-9be2-f7594c1f0dcf', '99af7291-f307-47b2-816e-a8b1baf33dd0');

まとめ

簡単にAPIをまとめてみました。カスタムスキル内でリストに登録されている項目を使用する時などに利用できるかと思うので実際に利用してみようと思います。