あなたのAlexaダッシュボード 設定

Alexaの買い物リストとTo Doリストにアクセスする

はじめに

Alexaのユーザーは現在、2つの標準リストにアクセスできます。Alexa To DoリストとAlexa買い物リストです。

ユーザーは、Alexaが使えるデバイスやAlexaアプリで音声を使用して、Alexaリストを確認したり修正したりできます。たとえば、ユーザーは家でAlexa買い物リストにアイテムを追加するようAlexaに伝えてから、店でAlexaアプリを使用してアイテムを確認し、それらにチェックを入れることができます。

サードパーティの開発者は、スキルにこれら2つのAlexaリストを読んだり修正したりする機能を搭載できます。詳細については、スキルにリスト管理機能を統合する方法について説明している「コードサンプルとスタートガイド」をご覧ください。

このドキュメントは、カスタムスキルをAlexaリストと統合する方法について、技術的な概要を提供します。カスタムスキルがまだない場合は、「カスタムスキルの構築手順」に従って作成できます。

これらのリスト管理機能をカスタムスキルに統合するには、次の手順に従います。

  1. Amazon開発者ポータルでスキルを構成し、スキルが「Lists Read」権限または「Lists Write」権限、もしくはその両方を必要とすることを示すようにします。
  2. ユーザーのAlexaリストを使用するユーザーインテントモデルを考案します。
  3. スキルサービスコードに、リスト管理機能を実装します。

ユーザーは、Alexaアプリの「スキル」セクションで、スキルに権限を与えます。ユーザーが権限を与えると、権限が明示的に取り消されるまで、スキルはユーザーのAlexaリストにアクセスできるようになります。ユーザーはいつでも、Alexaアプリのスキルのページにある「設定」で、スキルに許可したアクセスを変更することができます。

リクエストされた権限すべてをユーザーが許可したわけではない場合、スキルの開発者は適切に処理する必要があります。このような場合、音声プロンプトや権限不足カードを使用できます。このようなカードを使用する方法の詳細については、「権限が不足している場合のスキルの動作」をご覧ください。

権限の設定

スキルがユーザーのAlexaリストに読み取りまたは書き込みアクセスするには、スキルはAmazon開発者ポータルで設定できる適切な権限を持つ必要があります。

  1. Amazon開発者ポータルを開き、Alexa Skills Kitの「Get Started」を選択します。「Building Alexa Skills with the Alexa Skills Kit」ページが開きます。

  2. 既存のスキルの「Edit」をクリックし、左にある「Configuration」を選択します。

  3. Configuration」ページの「Permissions」セクションで、スキルの要件に応じて「Lists Read」または「Lists Write」チェックボックスもしくはその両方を選択します。スキルが必要とする以上の権限を要求しないでください。「Save」をクリックします。

Configuration for Lists
リストの構成

Alexaリストへのアクセス

これらのリスト管理機能にアクセスするために、スキルには、アクセスするAlexaリストのユーザーに固有の承諾トークンが必要です。このトークンは、セッション内リクエストにより取得できます。これはユーザーの音声リクエストです。

セッション内インテントリクエスト

ユーザーの承諾を取得すると、各リクエストにはユーザーの承諾トークンが含まれるようになります。したがって、Alexaからスキルへのセッション内インテントリクエストには、承諾トークンを含むuserオブジェクトが含まれています。このトークン値を取得し、リスト管理に関連するリクエストで使用する必要があります。

リクエスト全体の形式を次に示します。userオブジェクトはSystemオブジェクト内にネストされており、これがさらにcontextオブジェクト内にネストされています。また、userオブジェクトはsessionオブジェクト内にも複製されています。このようなリクエストのパラメーターの詳細については、次を参照してください。「リクエストボディの構文」。

{
  "version": "string",
  "session": {
    "new": true,
    "sessionId": "string",
    "application": {
      "applicationId": "string"
    },
    "attributes": {
      "string": {}
    },
    "user": {
      "userId": "amzn1.ask.account.<userId_value>",
         "permissions": {
             "consentToken": "Atza|MQEWY...6fnLok"
      },	  
      "accessToken": "string"
    }
  },
  "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"
    },
    "AudioPlayer": {
      "token": "string",
      "offsetInMilliseconds": 0,
      "playerActivity": "string"
    }
  },
  "request": {}
}

したがって、次のようになります。 consentToken = this.event.context.System.user.permissions.consentToken

参照:Alexaから送信されたリクエストを処理する

不足している権限の付与を処理する

スキルが「Lists Read」または「Lists Write」アクセスを必要とするのに、ユーザーがアクセスを許可しなかった場合、スキルの開発者はこのような状況をスキルサービスコード内で適切に処理する必要があります。ベストプラクティスとして、スキルにAlexaアプリで権限カードを表示させ、さらに音声プロンプトを使用して、ユーザーにAlexaアプリを確認し、必要なアクセスを許可するよう求めることができます。

スキルが使用できるカード形式の例を示します。この例では、ユーザーのAlexaリストへの書き込み権限を求めています。

{
    "version": "1.0",
    "response": {
        "card": {
            "type": "AskForPermissionsConsent",
            "permissions": [
                "write::alexa:household:list"                
            ]
        }
    }
}

リストの権限には読み取りと書き込みがあり、それぞれread::alexa:household:listwrite::alexa:household:listです。

リスト管理機能

リスト管理機能は、スキルの作成、読み取り、更新、および削除(CRUD)の操作を提供します。このAPIはユーザーのAlexaリストについての情報を明らかにします。また、リストトラバーサルをサポートしています。APIを通じて明らかになる各リストアイテムは、値やアイテムIDなどのプロパティを持ちます。

このAPIを呼び出すスキルは、API応答に新しいフィールドが含まれる場合に適切に対処できる弾力性が必要です。特に指定されていない場合、すべてのAPIパラメーターは文字列です。各itemIdはリスト内で一意です。

リスト管理のクイックリファレンス

リスト管理のドメイン(List Management Domain): https://api.amazonalexa.com/

APIメソッドURIエンドポイント
リストメタデータの取得GETv2/householdlists/
リストの取得GETv2/householdlists/{listId}/{status}
リストアイテムの取得GETv2/householdlists/{listId}/items/{itemId}
リストアイテムの更新PUTv2/householdlists/{listId}/items/{itemId}
新しいリストアイテムの作成POSTv2/householdlists/{listId}/items
リストアイテムの削除DELETEv2/householdlists/{listId}/items/{itemId}

リスト管理のためのHTTPメソッド

以下のAPIで、{listId}はユーザーのlistIdを表し、{itemId}は指定されたリストアイテムのitemIdを表します。

GetListsMetadata

ユーザーのすべてのAlexaリストのメタデータを取得します。

エンドポイント: https://api.amazonalexa.com/v2/householdlists/

リクエストのフォーマット

GET: v2/householdlists/
Authorization: Bearer auth_token_for_customer
Content-Type: application/json

応答のフォーマット

HTTP 200 OK, on success
{
    "lists":
    [
        {
            "listId": // list id (String)
            "name": // list name (String)
            "statusMap": [
                { "status": "active" // (Enum) ,  
                  "href": // active list items URL },
                { "status": "completed" // (Enum), 
                  "href": // completed list items URL }
            ]
        }
    ]
}

HTTP 403 Forbidden, if customer authorization token is not valid/expired
{
    "message": "request is unauthorized"
    "type": "Unauthorized"
}

HTTP 500 Internal Server Error, if Alexa encountered a server error 
{
    "message": // error message (String)
    "type": "InternalError"
}

GetList

ユーザーのAlexaリストを取得します。

GetListsMetadataの呼び出しで取得したlistIdを使用して、リクエストパス内のlistIdを指定します。クエリパス内で、status変数を指定する必要があります。これにより、アクティブなアイテムまたは完了したアイテムを取得することができます。GetList呼び出しの応答には、リストアイテムの次ページ(存在する場合)を取得するための相対URLが含まれます。GetList は、Alexaが決めたリストアイテムの順番で表示します。外部アプリは、Alexaリストアイテムを好みの順番で表示できます。

エンドポイント: https://api.amazonalexa.com/v2/householdlists/{listId}/{status}

リクエストのフォーマット

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

応答のフォーマット

HTTP 200 OK, on success

{
    "listId": // list id (String)
    "name": // list name (String)
    // default page size today is 100 and cannot be controlled by the client
    "items":
    [
	    {
            "id": // item id (String, limit 50 characters)
            "version": // item version (Positive integer)
            "value": // item value (String, limit 256 characters)
            "status": // item status (Enum: "active" or "completed")
            "createdTime": // created time (ISO 8601 time format w/time zone)
            "updatedTime": // updated time (ISO 8601 time format w/time zone)
            "href": // URL to retrieve the item (String)
         },
         ...
    ]
    "links": {
        "next": "v2/householdlists/{listId}/{status}?nextToken={nextToken}"
    }
}

HTTP 400 Bad Request, if input is malformed
{
    "message": // (String) (e.g., "invalid list items status)"
    "type": "InvalidInput"
}
 
HTTP 403 Forbidden, if a customer authorization token is not valid/expired
{
    "message": "request is unauthorized"
    "type": "Unauthorized"
}

HTTP 404 Not Found, if the list is not found
{
    "message": "list not found"
    "type": "ObjectNotFound"
}

HTTP 500 Internal Server Error, if Alexa encountered a server error
{
    "message": // error message (String)
    "type": "InternalError"
}

links/nextプロパティに何も入っていない場合、リクエスターはリストの最後まで達しています。リストアイテムは、アイテム作成日時に基づいて反時系列で返されます。

GetListItem

リスト内の単一のリストアイテムを取得します。

listIdGetListsMetadataの呼び出しで取得されます。

エンドポイント: v2/householdlists/{listId}/items/{itemId}

リクエストのフォーマット

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

応答のフォーマット


HTTP 200 OK, on success

{
    "id": // item id (String)
    "version": // item version when it was read (Positive integer)
    "value": // item value (String)
    "status": // item status (Enum: "active" or "completed")
    "createdTime": // created time (ISO 8601 time format with time zone)
    "updatedTime": // updated time (ISO 8601 time format with time zone)
    "href": // URL to retrieve the item (String)
}
 
HTTP 403 Forbidden, if a customer authorization token is not valid/expired
{
    "message": "request is unauthorized"
    "type": "Unauthorized"
}

HTTP 404 Not Found, if the list or list item is not found
{
    "message": // error message (String) (e.g., "item is not found")
    "type": "ObjectNotFound"
}

HTTP 500 Internal Server Error, if Alexa encountered a server error
{
    "message": // error message (String)
    "type": "InternalError"
}

UpdateListItem

リストアイテムがスキルにより更新された後、Alexaリストアイテムを更新します。

UpdateListItemの呼び出しにより、Alexaを介したユーザーのリストへの変更が分かります。

エンドポイント: v2/householdlists/{listId}/items/{itemId}

リクエストのフォーマット

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")
}

応答のフォーマット

HTTP 200 OK, on success
 
{
    "id": // item id (String)
    "version": // updated item version (Positive integer)
    "value": // item value (String, limit is 256 characters)
    "status": // item status (Enum: "active" or "completed")
    "createdTime": // created time (ISO 8601 time format with time zone)
    "updatedTime": // updated time (ISO 8601 time format with time zone)
    "href": // URL to retrieve the item (String)
}
 
HTTP 403 Forbidden, if a customer authorization token is not valid, or has expired
{
    "message": "request is unauthorized"
    "type": "Unauthorized"
}

HTTP 404 Not Found, if the list or list item is not found
{
    "message": // error message (String) (for example, "item is not found")
    "type": "ObjectNotFound"
}
 
HTTP 409 Conflict, if the item versions mismatch
{
    "message": "item versions mismatch"
    "type": "Conflict"
}

HTTP 500 Internal Server Error, if Alexa has encountered a server error
{
    "message": // error message (String)
    "type": "InternalError"
}

CreateListItem

新しいAlexaリストアイテムを作成します。

エンドポイント: v2/householdlists/{listId}/items

リクエストのフォーマット

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")
}

応答のフォーマット

HTTP 201 OK, on success
Location: v2/householdlists/{listid}/items/{itemId}
 
{
    "id": // item id (String)
    "version": // item version (Positive integer)
    "value": // item value (String, limit is 256 characters)
    "status": // item status (Enum: "active" or "completed")
    "createdTime": // created time (ISO 8601 time format with time zone)
    "updatedTime": // updated time (ISO 8601 time format with time zone)
    "href": // URL to retrieve the item (String)
}

HTTP 403 Forbidden, if a customer authorization token is not valid/expired
{
    "message": "request is unauthorized"
    "type": "Unauthorized"
}

HTTP 404 Not Found, if the list is not found
{
    "message": "list is not found"
    "type": "ObjectNotFound"
}

HTTP 500 Internal Server Error, if Alexa encountered a server error
{
    "message": // error message (String)
    "type": "InternalError"
}

DeleteListItem

Alexaリストアイテムを削除します。

エンドポイント: v2/householdlists/{listId}/items/{itemId}

リクエストのフォーマット

DELETE: v2/householdlists/{listId}/items/{itemId}

Authorization: Bearer auth_token_for_customer
Content-Type: application/json

応答のフォーマット

HTTP 200 OK, on success

HTTP 403 Forbidden, if a customer authorization token is not valid/expired
{
    "message": "request is unauthorized"
    "type": "Unauthorized"
}

HTTP 404 Not Found, if the list or list item is not found
{
    "message": // error message (String)
    "type": "ObjectNotFound"
}

HTTP 500 Internal Server Error, if Alexa encountered a server error
{
    "message": // error message (String)
    "type": "InternalError"
}

FAQ

Q:スキルでは、アカウントリンクとこれらのリスト管理機能の両方を使用できますか?

はい。この機能により、スキルの開発者はユーザーのAlexaリストを外部アプリ内で参照できます。アカウントリンクのセットアップの詳細については、「Alexaユーザーをシステムのユーザーにリンクする」を参照してください。

Q:Alexaのユーザーは、2つ以上のスキルに対してAlexa To Doリストと買い物リストへのアクセスを許可できますか?

はい。

Q:ユーザーは自分のAlexaリストを削除できますか?

ユーザーはAlexaリストを削除することはできません。ただし、ユーザーはAlexaリストのすべてのアイテムを削除することができます。

Q:ユーザーは、単一のAlexaリストへのアクセスを許可できますか?

いいえ、ユーザーはスキルに共有するリストを制限することはできません。ただし、スキルは関係するリストのみにアクセスすることを選択できます。

Q:これらのリスト管理機能は、カスタムリストのメタデータをサポートしていますか?

いいえ。

Q:Alexaユーザーは、自分のリストをAmazon内の他のユーザーと共有できますか?

はい、他のユーザーが同じAmazon家族アカウントの一員である場合は可能です。Amazon家族アカウントについては、「Alexa端末の家族プロフィール」をご覧ください。

次のステップ

コーディングに関するトピック

その他のトピック:

リファレンス:

コード例: