Alexaの買い物リストとやることリストにアクセスする

Alexaの買い物リストとやることリストにアクセスする

Alexaユーザーは2つのデフォルトリストにアクセスできます。 AlexaやることリストとAlexa買い物リストです。また、Alexaのユーザーは、サポートしているスキル内であればカスタムリストを作成したり管理したりできます。

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

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

スキルにリスト管理機能を統合する

ここでは、カスタムスキルをAlexaリストと統合する方法について、技術的な概要を説明します。カスタムスキルがまだない場合は、カスタムスキルのビルド手順に従って作成できます。

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

  1. 開発者コンソールでスキルを設定し、スキルがリストの読み込み権限またはリストへの書き込み権限、もしくはその両方が必要であることを設定します。
  2. ユーザーのAlexaリストを使用するユーザーインテントモデルをデザインします。
  3. スキルサービスコードに、リスト管理機能を実装します。

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

リクエストされた権限すべてをユーザーが許可したわけではない場合についても、適切に処理する必要があります。音声プロンプトや権限不足カードを使用できます。カードの使用については、不足している権限の付与を処理するを参照してください。

このドキュメントで説明しているリスト管理機能のほかに、スキルはリストイベントとスキルイベントにアクセスすることができます。これらのイベントはスキルの機能を拡張するために使用します。スキルサービスのSMAPIを使用するには、開発者はAlexa Skills Kitコマンドラインインターフェース（ASK CLI）を使用してスキルを管理する必要があります。一度ASK CLIでスキルを管理すると、開発者コンソールでの管理はできなくなります。

権限の設定

スキルがユーザーのAlexaリストを読み込んだり、またはリストに書き込んだりするには、開発者コンソールでスキルに適切な権限を設定する必要があります。スキルで提供されている機能やサービスをサポートするのに必要な場合、リストの読み込み権限またはリストへの書き込み権限をリクエストします。

  1. 開発者コンソールを使用してスキルを編集します。
  2. ビルド＞アクセス権限ページに移動します。
  3. スキルの要件に応じてリストの読み込みまたはリストへの書き込みチェックボックスのどちらか、もしくは両方を選択します。

Alexaリストへのアクセス

これらのリスト管理機能にアクセスするために、スキルにはアクセストークンが必要ですが、これはユーザーのAlexaリストにアクセスする権限をユーザーがスキルに与えたことを意味します。セッション内リクエストでこのトークンを取得します。たとえば、ユーザーの音声リクエストやセッション外リクエストの場合です。

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

スキルに送信される各リクエストには、スキルに与える権限をカプセル化するAPIアクセストークン（apiAccessToken）が含まれています。このトークン値を取得し、リスト管理に関連するリクエストで使用する必要があります。

以下は、リクエスト全体の例です。apiAccessTokenはSystemオブジェクトに含まれ、Systemオブジェクトはcontextオブジェクトに含まれます。このようなリクエストのパラメーターの詳細については、 リクエスト本文の構文を参照してください。

{
  "version": "1.0",
  "session": {
    "new": true,
    "sessionId": "amzn1.echo-api.session.[unique-value-here]",
    "application": {
      "applicationId": "amzn1.ask.skill.[unique-value-here]"
    },
    "attributes": {
      "key": "string value"
    },
    "user": {
      "userId": "amzn1.ask.account.[unique-value-here]",
      "accessToken": "Atza|AAAAAAAA...",
      "permissions": {
        "consentToken": "ZZZZZZZ..."
      }
    }
  },
  "context": {
    "System": {
      "device": {
        "deviceId": "string",
        "supportedInterfaces": {
          "AudioPlayer": {}
        },
        "persistentEndpointId" : "amzn1.alexa.endpoint.[unique-value-here]"    
      },
      "application": {
        "applicationId": "amzn1.ask.skill.[unique-value-here]"
      },
      "user": {
        "userId": "amzn1.ask.account.[unique-value-here]",
        "accessToken": "Atza|AAAAAAAA...",
        "permissions": {
          "consentToken": "ZZZZZZZ..."
        }
      },
      "person": {
        "personId": "amzn1.ask.person.[unique-value-here]",
        "accessToken": "Atza|BBBBBBB..."
      },
      "unit": {
        "unitId": "amzn1.ask.unit.[unique-value-here]",
        "persistentUnitId" : "amzn1.alexa.unit.did.[unique-value-here]"
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
    },
    "AudioPlayer": {
      "playerActivity": "PLAYING",
      "token": "audioplayer-token",
      "offsetInMilliseconds": 0
    }
  },
  "request": {}
}

したがって、次のようになります。

accessToken = this.event.context.System.apiAccessToken

詳細については、Alexaから送信されたリクエストを処理するを参照してください。

セッション外の対話

ユーザーの音声リクエスト以外でAlexaリストにアクセスする必要がある場合、アプリは以下の手順でセッション外のアクセストークンをリクエストできます。

  1. ClientIdとClientSecretを入力し、スキルメッセージAPIアクセストークンを取得します。これらのClientId値とClientSecret値を取得する方法については、開発者コンソール内のスキルのアクセス権限ページを参照してください。リクエストの形式の詳細については、スキルにメッセージを送信するようアプリケーションやサービスを設定するを参照してください。スキルをSMAPIで管理している場合でも、開発者コンソールでこれらの値を参照できます。スキルのリストに移動します。スキルに権限を設定すれば、スキルIDおよびクライアントシークレットを表示のリンクが表示されます。このリンクをクリックすると、スキルID、クライアントID、クライアントシークレットがポップアップに表示されます。

  2. アクセストークンを取得したら、アプリはスキルメッセージAPIアクセストークンとuserId値を使用してスキルメッセージAPIに非同期呼び出しを行います。この値はこれ以前のユーザー音声対話で取得されたものです。スキルメッセージAPIは、ユーザー同意トークンを使用してスキルをコールバックします。

セッション外トークンのワークフロー
セッション外トークンのワークフロー

スキルメッセージAPIアクセストークン

サードパーティアプリケーションの場合、スキルにメッセージを送信するには認可が必要です。以下で説明するようなHTTPSリクエストを使用したAPIで認可を取得します。

リクエストの形式

このセクションでは、リクエストの形式について説明します。

HTTPヘッダー

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
 
パラメーター 説明 例
Content-Type リソースのコンテンツタイプです。application/x-www-form-urlencodedである必要があります Content-Type: application/x-www-form-urlencoded

リクエスト本文の構文

grant_type=client_credentials&client_id=(clientID)&client_secret=(clientSecret)&scope=alexa:skill_messaging

リクエスト本文のパラメーター

 
パラメーター 説明 例
grant_type 値はclient_credentialsである必要があります。 grant_type=client_credentials
client_id ClientIdの値です。 client_id=amzn1.iba-client...
client_secret ClientSecretの値です。 client_secret=...
scope 値はalexa:skill_messagingである必要があります。 scope=alexa:skill_messaging

cURLリクエストのサンプル

curl -k -X POST -H
 'Content-Type: application/x-www-form-urlencoded' -d
'grant_type=client_credentials&client_id=xxxx&client_secret=yyyy&scope=alexa:skill_messaging'
 https://api.amazon.com/auth/o2/token

応答の形式

リクエストが正常に完了しなかった場合、200以外のエラーステータスコードを受信します。200以外のコードの場合、応答メッセージのJSONObject本文に以下のパラメーターが含まれることがあります。

reason: <<リクエストが受け取られなかった理由>>

正常な応答形式は次のとおりです。

HTTPヘッダー

X-Amzn-RequestId: d917ceac-2245-11e2-a270-0bc161cb589d
 Content-Type: application/json

応答本文の構文

{
  "access_token": "Atc|MQEWYJxEnP3I1ND03ZzbY_NxQkA7Kn7Aioev_OfMRcyVQ4NxGzJMEaKJ8f0lSOiV-yW270o6fnkI",
  "expires_in": 3600,
  "scope": "alexa:skill_messaging",
  "token_type": "Bearer"
}

リクエスト本文のパラメーター

 
パラメーター 説明 例
access_token すべてのリクエストに使用する必要があるアクセストークンです。 "access_token":"Atc|MQEWYJxEnP3I1ND03Zz..."
expires_in アクセストークンの有効期間（秒）です。3600の場合、アクセストークンは応答が生成されてから1時間で無効になります。 "expires_in":3600
scope 値はalexa:skill_messagingになります。 "scope":"alexa:skill_messaging"
token_type ベアラートークンのみがサポートされます。 "token_type":"Bearer"

エラー

ステータスコード型説明
400INVALID_REQUESTこの応答には、以下の理由が考えられます。
- 認可サーバーでコンテンツタイプがサポートされていません。つまり、これはapplication/x-www-form-urlencodedではありません。
- リクエストに次の必須パラメーターがありません：grant-type、scope、client_id、client_secret
- リクエストの形式が正しくありません。
400 UNAUTHORIZED_CLIENT クライアントは、リクエストされた操作を行うことを認可されていません。
400 UNSUPPORTED_GRANT_TYPE grant種別が認可サーバーでサポートされていません。つまり、これはclient_credentialsではありません。
400 INVALID_SCOPE リクエストされたスコープが無効です。つまりこれはalexa:skill_messagingではありません。
401 INVALID_CLIENT クライアントの認証に失敗しました。
500 SERVER_ERROR 内部サーバーエラーです。リクエスターはリクエストを再試行できます。
503 SERVICE_UNAVAILABLE サーバーが一時的に使用できません。リクエスターは応答のRetry-Afterヘッダーを参照して再試行する必要があります。Retry-After値の形式については、HTTP/1.1仕様のセクション14.37を参照してください。

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

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

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

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

読み込みと書き込みに必要なリスト権限はそれぞれalexa::household:lists:readとalexa::household:lists:writeです。

リスト管理機能

リスト管理機能を使用すると、スキルの作成、読み取り、更新、および削除（CRUD）の操作が可能です。このAPIはユーザーのAlexaリストについての情報を明示します。また、リストトラバーサルをサポートしています。APIから明示される各リスト項目には、値や項目IDなどのプロパティがあります。

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

制限

リクエストはスキルごとに25 TPSに調整されます。そのため、スキルは/v2/householdlistsのリストAPIに対して1秒あたり最大25リクエストを行うことができます。この制限を超えたリクエストは、「Rate exceeded」のメッセージとともにHTTP 400のエラーコードを受信します。その後、このリクエストは再試行される可能性があります。

リストAPIの使用に関する一般的な注釈

  1. ユーザーのデフォルトリストへの参照は、Alexaのやることリストと買い物リストも参照します。
  2. このドキュメントで示す各APIは、デフォルトリストとカスタムリストの両方で使用できます。
  3. エラー応答メッセージ内のテキストは変更される可能性があるため、エラーに対するスキルの応答を管理するには、開発者はエラーメッセージのテキストではなくエラーコードを信頼する必要があります。
  4. HTTP 500 InternalErrorにより、スキルはリクエストの再試行が可能になります。
  5. アーカイブリストは読み取り専用リストです。アーカイブリストの項目は読み取りのみ可能で、削除や変更はできません。
  6. カスタムリストが削除された場合、スキルはリスト削除イベントを取得しますが、削除リストの項目に関する個々の項目削除イベントは取得しません。

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

リスト管理のドメイン：https://api.amazonalexa.com/

このドメインにエンドポイントを追加します。

APIMethodURI Endpoint
Get lists metadataGETv2/householdlists/
Get a listGETv2/householdlists/{listId}/{status}
Get a list itemGETv2/householdlists/{listId}/items/{itemId}
Update a list itemPUTv2/householdlists/{listId}/items/{itemId}
Create a new list itemPOSTv2/householdlists/{listId}/items
Delete a list itemDELETEv2/householdlists/{listId}/items/{itemId}
Create a custom listPOSTv2/householdlists/
Update a custom list's `name` or `status`PUTv2/householdlists/{listId}
Delete a custom listDELETEv2/householdlists/{listId}

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

以下のAPIでは、{listId}はユーザーのlistIdを参照し、{itemId}は指定のリスト項目のitemIdを参照します。

デフォルトのAlexaリストであるやることリストと買い物リストは、常にAPI応答内のカスタムリストの先頭に表示されます。AlexaやることリストとAlexa買い物リストはアーカイブしたり削除したりできません。

エラーが発生した場合、アプリは応答にエラーコードを使用する必要があります。メッセージ内のテキストは変更される可能性があるため、信頼するべきではありません。

GetListsMetadata

ユーザーのデフォルトリストを含めたすべてのユーザーリストのメタデータを取得します。応答には以下が適用されます。

  • デフォルトリストは、常にAPI応答内のすべてのカスタムリストの先頭に表示されます。
  • デフォルトリストのバージョンは常に1であり、デフォルトリストの状態は常にアクティブです。

エンドポイント：v2/householdlists/

リクエストの形式

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

応答の形式

HTTP 200 OK（成功時）

{
    "lists": [
        // デフォルトの 買い物 リスト の詳細
        {
            "listId": "shopping_list_list_id",
            "name": "Alexa shopping list",
            "state": "active",
            "version": 1,
            "statusMap": [
                {
                    "href": "url",	// リストに アクティブ リスト 項目 を取得する ための URL です 。
                    "status": "active"
                },
                {
                    "href": "url",	// リストに 完了した リスト 項目 を取得する ための URL です。
                    "status": "completed"
                }
    ]
        },
        // デフォルトの やること リストの 詳細
        {
            "listId": "todo_list_list_id",
            "name": "Alexa to-do list",
            "state": "active",
            "version": 1,
            "statusMap": [
                {
                    "href": "url",
                    "status": "active"
                },
                {
                    "href": "url",
                    "status": "completed"
                }
            ]
        },
        // カスタム リストの 詳細
        {
            "listId": "ff097d45-c098-44af-a2e9-7dae032b270b", // List id, String
            "name": "test-list-name-veba",			  // リスト 名, 文字列
            "state": "active",					  // リストの 状態、 列挙
            "version": 7,
            "statusMap": [
                {
                    "href": "url",	// リストに アクティブ リスト 項目 を取得する ための URL です 。
                    "status": "active"
                },
                {
                    "href": "url",	// リストに 完了した リスト 項目 を取得する ための URL です。
                    "status": "completed"
                }
            ]
        },
        ...
    ]
}

HTTP 403 Forbidden（ユーザー認可トークンが無効または期限切れの場合）

{
    "Message": "リクエストは認可されていません。"
}

HTTP 500 Internal Server Error（Alexaがサーバーエラーに遭遇した場合）

{
    "message": "",
    "type": "InternalError"
}

GetList

GetList APIは、リクエストされた状態とともに、リストの項目を含むリストのメタデータを取得します。以下のようにエンドポイントを作成します。

  • GetListsMetadataに対する呼び出しで取得したlistIdを使用して、リクエストパスのlistIdを指定します。
  • 「active」または「completed」の項目を指定するために、値が「active」か「completed」のどちらかになる、クエリーパスのstatus変数を指定します。

GetList呼び出しの応答には、リスト項目の次ページ（存在する場合）を取得するための相対URLが含まれます。GetListは、Alexaが決めたリスト項目の順番で表示されます。外部アプリは、Alexaリスト項目を好みの順番で表示できます。

エンドポイント：v2/householdlists/{listId}/{status}

listIdはユーザーのlistIdの値です。statusは「active」または「completed」です。

リクエストの形式

GET v2/householdlists/{listId}/{status}
Authorization: Bearer auth_token_for_customer
Content-Type: application/json

応答の形式

HTTP 200 OK（成功時）

{
    "listId": , // リストID（文字列）
    "name":   , // リスト名（文字列）
    "state":  , // "active" または "archived" （列挙）
    "version":, // リストのバージョン（文字列）
    "items":
    [
	    {
            "id": , // 項目ID（文字列、最大256文字）
            "version": , // 項目のバージョン（正の整数）
            "value": , // 項目の値（文字列、最大256文字）
            "status": , // 項目のステータス（列挙値： "active" または "completed"）
            "createdTime": , // 作成日時 形式 Wed Jul 19 23:24:10 UTC 2017
            "updatedTime": , // 更新日時 形式 Wed Jul 19 23:24:10 UTC 2017
            "href": // 項目を取得するためのURL（文字列）
         },
         ...
    ],
    "links": {
        "next": "v2/householdlists/{listId}/{status}?nextToken={nextToken}"
    }
}

正常な応答には以下が適用されます。

  • リスト項目のデフォルトのページサイズは100であり、クライアントはこれを変更できません。
  • linksのnextプロパティが空またはnullの場合、リクエストはリストの最後に達したことを意味します。
  • リスト項目は、項目作成日時に基づいて反時系列で返されます。
  • この時点では、リスト項目の順番を変えることはできません。

HTTP 400 Bad Request（入力が不正な形式である場合）

{
    "message": "無効な入力です。",
    "type": "InvalidInput"
}

HTTP 403 Forbidden（ユーザーがリストを所有していない場合）

{
    "message": "指定のリストIDはユーザーが所有しているものではありません。",
    "type": "Unauthorized"
}

HTTP 404 Not Found（リストが見つからない場合）

{
    "message": "リストIDが存在しません。",
    "type": "ObjectNotFound"
}

HTTP 500 Internal Server Error（Alexaがサーバーエラーに遭遇した場合）

{
    "message": "内部エラーです。",
    "type": "InternalError"
}

CreateList

このAPIはカスタムリストを作成します。新しいリストの名前は既存のリストの名前と異なるものにする必要があります。

  • 提供されるリスト名は両端でトリミングされ、この文字列をリストが既存のものであるかどうかを確認するために使用します。
  • リスト名では大文字と小文字が区別されます。つまり、リスト名は小文字に変換されません。
  • リスト名チェックでは大文字と小文字は区別されません。
  • このAPIはアーカイブリストの作成を許可しません。取得した状態に関係なく、APIはアクティブリストを作成します。
  • このリスト名チェックはアクティブリストに対してのみ実行可能です。同じ名前のアーカイブリストが存在している場合、このAPIはアクティブリストの作成を許可します。
  • アクティブリストの数は、1人のユーザーにつき、デフォルトリストも含めて100個のみです。

エンドポイント：v2/householdlists/

リクエストの形式

POST v2/householdlists/

Authorization: Bearer auth_token_for_customer
Content-Type: application/json

{
    "name": "my Amazon list", 	// リスト 名、 文字列、 256 文字
    "state": "active" 		// リスト ステータス, 列挙, "active" のみ
}

応答の形式

HTTP 201 OK（成功時）

{
    "listId": "09d9d7df-05be-438c-veba-9d32968b4509",	// リスト id、 文字列
    "name": "my Amazon list",				            // リスト 名, 文字列
    "state": "active",					                // リストの 状態、 列挙
    "version": 1,						                // バージョン, 長さ
    "statusMap": [
        {
            "href": "url",		// リストに アクティブ リスト 項目 を取得する ための URL です 。
            "status": "active"
        },
        {
            "href": "url",		// リストに 完了した リスト 項目 を取得する ための URL です 。
            "status": "completed"
        }
    ]
}

HTTP 400 Bad Request（リスト名が長すぎる、またはリスト名が空であるなど、入力が無効である場合）

{
    "message": "無効な入力です。",
    "type": "InvalidInput"
}

HTTP 400 Bad Request（ユーザーがリストの最大数に達した場合）

{
    "message": "リストの上限に到達しました",
    "type": "MaxLimitReached"
}

HTTP 403 Forbidden（ユーザー認可トークンが無効または期限切れの場合）

{
    "message": "リクエストは認可されていません",
    "type": "Unauthorized"
}

HTTP 409 Conflict（同じ名前のリストがすでに存在している場合）

{
    "message": "リスト名はすでに存在します。",
    "type": "NameConflict"
}

HTTP 500 Internal Server Error（Alexaがサーバーエラーに遭遇した場合）

{
    "message": "内部エラーです。",
    "type": "InternalError"
}

UpdateList

このAPIはカスタムリストを更新します。リストのnameまたはstateのみ更新できます。Alexaのユーザーはアーカイブリストをアクティブリストに変換できます。

  • アクティブリストのリスト名を更新します。
  • アクティブリストをアーカイブします。
  • アーカイブリストをアクティブリストに戻します。

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

listIdはGetListsMetadata呼び出しで取得したユーザーのlistIdの値です。

リクエストの形式

PUT v2/householdlists/{listId}  //{listId}がユーザーのリストidの場合

Authorization: Bearer auth_token_for_customer
Content-Type: application/json

{
    "name": // 新規リスト名（文字列、最大の長さは256文字）,
    "state" : // リストのステータス、"active"または"archived"（列挙）,
    "version" : // リストのバージョン（取得時）（long）
}

応答の形式

HTTP 200 OK（成功時）

{
    "listId": "09d9d7df-05be-438c-veba-9d32968b4509",	// リスト id、 文字列
    "name": "新規リスト名",				// リスト 名, 文字列
    "state": "active",					// リストの 状態、 列挙
    "version": 8,						// 更新 バージョン, Long
    "statusMap": [
        {
            "href": "url",		// リストに アクティブ リスト 項目 を取得する ための URL です 。
            "status": "active"
        },
        {
            "href": "url",		// リストに 完了した リスト 項目 を取得する ための URL です 。
            "status": "completed"
        }
    ],
}

HTTP 400 Bad Request（リスト名が空である、または長すぎるなど、入力が無効である場合）

{
    "message": "無効な入力です。",
    "type": "InvalidInput"
}

HTTP 400 Bad Request（ユーザーがリストの最大数に達した場合）

{
    "message": "リストの上限に到達しました",
    "type": " MaxLimitReached"
}

HTTP 403 Forbidden（アーカイブリストの復元ではなく更新が試みられた場合）

{
    "message": "アーカイブリストの更新は、リストの復元を除いて許可されていません。",
    "type": "ImmutableDataModification"
}

HTTP 403 Forbidden（ユーザー認可トークンが無効または期限切れの場合）

{
    "Message": "リクエストは認可されていません。"
}

HTTP 403 Forbidden（ユーザーがリストを所有していない場合）

{
    "message": "指定のリストIDはユーザーが所有しているものではありません。",
    "type": "Unauthorized"
}

HTTP 404 ListNotFound（listIdが見つからない場合）

{
    "message": "リストIDが存在しません。",
    "type": "ObjectNotFound"
}

HTTP 409 Conflict（同じ名前のリストが存在している場合）

{
    "message": "リスト名はすでに存在します。",
    "type": "NameConflict"
}

HTTP 409 Conflict（取得したリストのバージョンが最新のリストのバージョンと一致しない場合）

{
	"message": "無効なリストバージョンです。",
    "type": "VersionConflict"
}

HTTP 500 Internal Server Error（Alexaがサーバーエラーに遭遇した場合）

{
    "message": "内部エラーです。",
    "type": "InternalError"
}

DeleteList

このAPIはユーザーのカスタムリストを削除します。

  • 空ではないリストを削除できます。
  • アーカイブリストを削除できます。
  • ユーザーのデフォルトリストは削除できません。
  • デフォルトリストを削除しようとすると、権限なしという例外が発生します。
  • すでに削除されたリストを削除しようとすると、「リストが見つかりません（List not found）」という例外が発生します。

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

リクエストの形式

DELETE: v2/householdlists/{listId}  //{listId}がユーザーのリストidの場合

Authorization: Bearer auth_token_for_customer
Content-Type: application/json

応答の形式

HTTP 200 OK（成功時）

HTTP 403 Forbidden（ユーザー認可トークンが無効または期限切れの場合）

{
    "message": "リクエストは認可されていません。",
    "type": "Unauthorized"
}

HTTP 403 Forbidden（デフォルトのAlexaリストを削除しようとした場合）

{
    "message": "Alexaのやることリストまたは買い物リストを削除できません。",
    "type": "Unauthorized"
}

HTTP 403 Forbidden（ユーザーがリストを所有していない場合）

{
    "message": "指定のリストIDはユーザーが所有しているものではありません。",
    "type": "Unauthorized"
}

HTTP 404 Not Found（取得したlistIdのリストが見つからない場合）

{
    "message": "リストIDが存在しません。",
    "type": "ObjectNotFound"
}

HTTP 500 Internal Server Error（Alexaがサーバーエラーに遭遇した場合）

{
    "message": // エラーメッセージ（文字列）,
    "type": "InternalError"
}

GetListItem

このAPIは、listIdとitemIdによってすべてのリストから項目を1つ取得するために使用できます。

このAPIはアーカイブリストからリスト項目を読み取ることができます。

削除されたリストからリスト項目を読み取ろうとすると、ObjectNotFoundという例外がスローされます。

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

  • listIdはGetListsMetadata呼び出しによって取得します。
  • リストのitemIdはGetList呼び出しによって取得します。

リクエストの形式

GET v2/householdlists/{listId}/items/{itemId}
{listId}がユーザーのリストidで、{itemId}が項目idの場合

Authorization: Bearer auth_token_for_customer
Content-Type: application/json

応答の形式

HTTP 200 OK（成功時）

{
   "id": 		// 項目 id (文字列, 上限 60 文字)
   "version": 	// 項目 バージョン (正の 整数)
   "value": 	// 項目 値 (文字列, 上限 256 文字)
   "status": 	// 項目 ステータス (列挙: "active" または "completed")
   "createdTime":	// 作成 日時 (Wed Sep 27 10:46:30 UTC 2017)
   "updatedTime":	// 更新 日時 (Wed Sep 27 10:46:30 UTC 2017)
   "href": 	// 項目 を 取得する ための URLです (文字列)
}

HTTP 403 Forbidden（ユーザー認可トークンが無効または期限切れの場合）

{
    "message": "リクエストは認可されていません。",
    "type": "Unauthorized"
}

HTTP 403 Forbidden（取得したlistIdをユーザーが所有していない場合）

{
    "message": "項目IDは指定のユーザーは所有していません。",
    "type": "Unauthorized"
}

HTTP 404 Not Found（取得したlistIdのリストが見つからない場合）

{
    "message":"リストIDまたは項目IDは存在しません。",
    "type": "ObjectNotFound"
}

HTTP 500 Internal Server Error（Alexaがサーバーエラーに遭遇した場合）

{
    "message": "内部エラーです。",
    "type": "InternalError"
}

CreateListItem

このAPIは、アーカイブリストまたはデフォルトリストの項目を作成します。このAPIには以下の制限が適用されます。

  • 項目値を空にすることはできません。たとえば、項目値をスペースだけにすることはできません。
  • 項目名はトリミングされず、大文字と小文字は変換されず、そのままになります。そのため、2つのリスト項目が、実際は違う名前なのに同じ名前であるかのように見える場合があります。
  • アーカイブリストに項目は追加できません。

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

  • ユーザーのlistIdはGetListsMetadata呼び出しによって取得します。

リクエストの形式

POST v2/householdlists/{listId}/items
Authorization: Bearer auth_token_for_customer
Content-Type: application/json

{
    "value": "my item", //項目値, （最大256文字までの文字列の説明が含まれる）
    "status": "completed" // 項目ステータス（列挙： "active" または "completed"）
}

応答の形式

HTTP 201 OK（成功時）場所：v2/householdlists/{listid}/items/{itemId}

{
    "id": // 項目 id （文字列, 上限 60 文字）,
    "version": // 項目 バージョン （正の 整数）,
    "value": // 項目 値 （文字列, の 上限は 256 文字です）,
    "status": // 項目ステータス（列挙："active" または "completed"）,
    "createdTime": // 作成日時 （ISO 8601 タイムゾーンを含む時間形式）,
    "updatedTime": // 更新日時（ISO 8601 タイムゾーンを含む時間形式）
    "href": // 項目を取得するためのURL（文字列）
}

HTTP 403 Forbidden（ユーザー認可トークンが無効または期限切れの場合）

{
    "Message": "リクエストは認可されていません。"
}

HTTP 403 Forbidden（取得したlistId1をユーザーが所有していない場合）

{
    "message": "指定のリストIDはユーザーが所有しているものではありません。",
    "type": "Unauthorized"
}

HTTP 403 Forbidden（アーカイブリストに対して項目の追加が試みられた場合）

{
    "Message": "アーカイブリストの項目の作成は許可されていません。",
    "type": "ImmutableDataModification"
}

HTTP 404 Not Found（リストが見つからない場合）

{
    "message": "リストが見つかりません",
    "type": "ObjectNotFound"
}

HTTP 500 Internal Server Error（Alexaがサーバーエラーに遭遇した場合）

{
    "message": "内部エラー",
    "type": "InternalError"
}

UpdateListItem

このAPIは項目値または項目のステータスを更新するために使用されます。

このAPIには以下の条件が適用されます。

  • 項目値を空にすることはできません。たとえば、項目値をスペースだけにすることはできません。
  • 項目名はトリミングされず、大文字と小文字は変換されず、そのままになります。そのため、2つのリスト項目が、実際は違う名前なのに同じ名前であるかのように見える場合があります。
  • アーカイブリストに項目は追加できません。
  • 項目値やステータスを何も変更せずに更新しようとすると、更新されません。

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

listIdはユーザーのリストIDであり、itemIdはそのリスト内で更新される項目IDです。

リクエストの形式

PUT v2/householdlists/{listId}/items/{itemId}
Authorization: Bearer auth_token_for_customer
Content-Type: application/json

{
    "value": "my item", // 新しい項目値（文字列、256文字）
    "status": "completed", // 項目ステータス（列挙： "active" または "completed"）
	"version": 7 // 項目 バージョン (  読み取り 時 (正の 整数)
}

応答の形式

HTTP 200 OK（成功時）

{
   "id": 		// 項目 id (文字列, 上限 60 文字)
   "version": 	// 項目 バージョン (正の 整数)
   "value": 	// 項目 値 (文字列, 上限 256 文字)
   "status": 	// 項目 ステータス (列挙: "active" または "completed")
   "createdTime":	// 作成 日時 (Wed Sep 27 10:46:30 UTC 2017)
   "updatedTime":	// 更新 日時 (Wed Sep 27 10:46:30 UTC 2017)
   "href": 	// 項目 を 取得する ための URLです (文字列)
}

HTTP 400 Bad Request（項目値が長すぎる、空であるなど、入力が無効な場合）

{
    "message": "リスト項目を更新するには、有効なバージョンを指定する必要があります", // など
    "type": "InvalidInput"
}

HTTP 403 Forbidden（ユーザー認可トークンが無効または期限切れの場合）

{
    "Message": "リクエストは認可されていません。"
}

HTTP 403 Forbidden（項目をアーカイブリストに追加しようとした場合）

{
    "Message": "アーカイブリストの項目の更新は許可されていません。",
    "type": "ImmutableDataModification"
}

HTTP 403 Forbidden（ユーザーがリストを所有していない場合）

{
    "message": "指定のリストIDはユーザーが所有しているものではありません。",
    "type": "Unauthorized"
}

HTTP 404 Not Found（listIdまたはitemIdが存在しない場合）

{
    "message": "リストIDまたは項目IDは存在しません。",
    "type": "ObjectNotFound"
}

HTTP 409 Conflict（取得した項目のバージョンがAlexa内の最新の項目のバージョンと一致しない場合）

{
    "message": "無効な項目バージョンです。",
    "type": "VersionConflict"
}

HTTP 500 Internal Server Error（Alexaがサーバーエラーに遭遇した場合）

{
    "message": "内部エラーです。",
    "type": "InternalError"
}

DeleteListItem

このAPIは、指定したリストの項目を削除します。

  • ユーザーのlistIdはGetListsMetadata呼び出しによって取得します。
  • ユーザーの itemIdはGetList呼び出しによって取得します。

このAPIには以下の条件が適用されます。

  • アーカイブリストのリスト項目は削除できません。
  • このAPIは、べき等ではありません。すでに削除されたリスト項目を削除しようとすると、オブジェクトが見つからない（Object not found）という例外が発生します。
  • 削除中にリスト項目が更新された場合、内部エラーが発生し、リクエストが再試行される場合があります。

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

リクエストの形式

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

Authorization: Bearer auth_token_for_customer
Content-Type: application/json

応答の形式

HTTP 200 OK（成功時）

HTTP 403 Forbidden（ユーザー認可トークンが無効または期限切れの場合）

{
    "Message": "リクエストは認可されていません。"
}

HTTP 403 Forbidden（項目をアーカイブリストから削除しようとした場合）

{
    "Message": "アーカイブリストの項目の削除は許可されていません。",
    "type": "ImmutableDataModification"
}

HTTP 403 Forbidden（ユーザーがリストを所有していない場合）

{
    "message": "指定のリストIDはユーザーが所有しているものではありません。",
    "type": "Unauthorized"
}

HTTP 404 Not Found（リストまたはリスト項目が見つからない場合）

{
    "message": "リストIDまたは項目IDは存在しません。",
    "type": "ObjectNotFound"
}

HTTP 500 Internal Server Error（Alexaがサーバーエラーに遭遇した場合）

{
    "message": "内部エラーです。",
    "type": "InternalError"
}

サンプルコード

スキルにリストを組み込む方法のサンプルコードについては、Alexaリストへのアクセスデモを参照してください。