データストアREST APIリファレンス

データストアREST APIリファレンス

画面付きのAlexa搭載デバイスでデータストアを更新するには、データストアREST APIを使用します。スキルに送信されたリクエストやスキルセッション外から、データストアに更新をプッシュできます。データストアとは、デバイスにローカルにインストールされ、Alexa Presentation Language（APL）ドキュメントからデータバインディングを使用してアクセスできるデータを格納する領域です。ウィジェットでは、データストアを使用することで、スキルにリクエストを送信して応答を待つ必要なくコンテンツを表示できます。

特定のデバイスリストのデータストアや、特定のユーザーのデータストアを更新できます。

ウィジェットの詳細については、ウィジェットとAlexa Presentation Language（APL）の概要を参照してください。

データストアの構造

デバイス上のデータストアは、リージョン、名前空間、キーによって編成されます。リージョンには複数の名前空間を含めることができ、名前空間には複数のキーを含めることができます。各キーに、データを含むオブジェクトが格納されます。各データストアコマンドには、必要に応じてnamespaceとkeyを指定するプロパティがあります。データストアAPIは、スキルIDに基づいてスキルのリージョンを決定します。スキルでは、ほかのスキルのデータストアにアクセスすることはできません。詳細については、データバインディングとデータストアを参照してください。

データストアの制限

データストアには、次の制限が適用されます。

  • スキルがデバイス上に保存できるデータは最大1MBです。この制限値はスキル単位で適用され、そのスキルに関連付けられているすべてのウィジェットで共有されます。リージョン内の各項目は、namespaceとkeyの名前も含めて、スキルで使用されるストレージのサイズにカウントされます。
  • スキルからデータストアにデータを書き込む場合、1秒あたりのトランザクション数（TPS）が25を超えることはできません。

APIエンドポイント

スキルのリージョンに基づいて、以下のエンドポイントのいずれかを使用します。

  • 北米：https://api.amazonalexa.com
  • ヨーロッパ：https://api.eu.amazonalexa.com
  • 極東：https://api.fe.amazonalexa.com

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon（LWA）から取得したアクセストークンが入ります。詳細については、スキルの認証情報を含むアクセストークンを取得する操作を参照してください。リクエスト本文で、スコープをalexa::datastoreに設定します。

操作

データストアAPIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

キャンセル

POST /v1/datastore/queue/<queuedResultId>/cancel

コマンド

POST /v1/datastore/commands

キュー内の結果のクエリ

GET /v1/datastore/queue/<queuedResultId>?maxResults={maxResults}&nextToken={nextToken}

キャンセル

キュー内の指定された結果に対する保留中のリクエストをキャンセルします。コマンド操作によって発行された以前のリクエストをキャンセルするには、このコマンドを使用します。

リクエスト

リクエストをキャンセルするには、/v1/datastore/queue/<queuedResultId>/cancelリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v1/datastore/queue/<queuedResultId>/cancel
Content-Type: application/json
Authorization: Bearer {access_token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

queuedResultId

パス

キュー内にあるオフラインデバイスへの配信を照会するための一意の識別子です。この識別子は、コマンド操作への応答から取得します。

文字列

◯

access_token

ヘッダー

スキルのアクセストークンです。アクセストークンを取得するには、クライアント認証情報とスコープを使用します。詳細については、認証を参照してください。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 204 No Contentが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

204 No Content

保留中のリクエストが正常にキャンセルされました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • COMMANDS_DELIVERED - 保留中のコマンドは配信されました。
  • CONCURRENCY_ERROR - 保留中のコマンドの配信が同時に試行されています。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_ACCESS_TOKEN - アクセストークンが有効期限切れまたは無効です。

403 Forbidden

認可トークンは有効ですが、リクエストされた操作が許可されていないことを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • DATA_STORE_SUPPORT_REQUIRED - スキルにAlexa.DataStoreインターフェースのサポートが設定されていません。
    必要なインターフェースをサポートするようにスキルをアップデートしてください。詳細については、ウィジェット用のインターフェースを有効にするを参照してください。

429 Too many requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用してください。

500

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用してください。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • DATASTORE_UNAVAILABLE - 予期しない内部サービスエラーが発生しました。

コマンド

指定された一連のコマンドを実行して、デバイスまたはユーザーのリストのデータストアを更新します。実行できるコマンドの詳細については、データストアコマンドリファレンスを参照してください。デバイスがオフラインの場合、コマンドはデバイスがオンラインに戻るまでキューに入れられます。キューに入れられたコマンドのステータスを取得するには、キュー内の結果のクエリを使用します。

リクエスト

データストアを更新するコマンドのセットを実行するには、/v1/datastore/commandsリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v1/datastore/commands
Content-Type: application/json
Authorization: Bearer {access_token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

access_token

ヘッダー

スキルのアクセストークンです。アクセストークンを取得するには、クライアント認証情報とスコープを使用します。詳細については、認証を参照してください。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

{
  "commands": [
    {
      "type": "PUT_OBJECT",
      "namespace": "NamespaceMainPage",
      "key": "keyMainPage",
      "content": {
        "mainPageContent": {
          "lastUpdated": "この更新は2023年4月17日に送信されました。"
        }
      }
    }
  ],
  "target": {
    "type": "DEVICES",
    "items": [
      "amzn1.ask.device.1",
      "amzn1.ask.device.2"
    ]
  },
  "attemptDeliveryUntil": "2024-01-31T10:00:00.00Z"
}

リクエスト本文のプロパティ

プロパティ 説明 型 必須

commands

データストアを更新するために実行する、順序付けされたコマンドのコレクションです。コマンドの形式の詳細については、データストアコマンドを参照してください。

データストアコマンドの配列

◯

target

コマンドのターゲットを識別します。デバイスIDのリストか、単一のユーザーIDを指定します。

Targetオブジェクト

◯

attemptDeliveryUntil

指定すると、初回試行時にデバイスにアクセスできなかった場合、Alexaは追加でコマンドの配信を試みます。最大値は、リクエストを送信してから48時間後です。応答本文のdispatchResultsを調べると、リクエスト内にアクセス不可能なデバイスがなかったかどうかを確認できます。
ISO 8601の形式（YYYY-MM-DDThh:mm:ssZ）で定義します。

指定しない場合、Alexaは、アクセスできないデバイスへのコマンドの再配信を試みません。

文字列

×

応答

正常に完了すると、HTTP 200 OKと共に、デバイスごとの結果が返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

次の例は、2台のデバイスの更新を試みたコマンド操作の応答本文を示しています。この例では、Alexaは最初のデバイスを更新しましたが、2台目のデバイスは利用不可能だったために更新できませんでした。

{
  "results": [
    {
      "deviceId": "amzn1.ask.device.1",
      "type": "SUCCESS"
    },
    {
      "deviceId": "amzn1.ask.device.2",
      "type": "DEVICE_UNAVAILABLE",
      "message": "AOGS: Send directive failure: Device unreachable"
    }
  ],
  "queuedResultId": "<この結果のID>"
}

応答本文のプロパティ

プロパティ 説明 型

results

ターゲットのユーザーまたはデバイスごとの結果のリストです。この配列の各項目は、指定されたデバイスで操作が成功したかどうかを示します。

results配列の項目は、リクエストのターゲットのタイプによって異なります。

  • DEVICES：results配列の項目の数と順序は、target.items配列のデバイスIDの順序と同じです。
  • USER：results配列の項目の数と順序は、指定されたユーザーに関連付けられているデバイスの数によって決まり、変動する可能性があります。

オブジェクトの配列

results[].deviceId

Alexaが更新を試みたデバイスのIDです。
amzn1.ask.device.{id}というAmazon Common Identifier（ACI）形式で表されます。

文字列

results[].type

amzn1.ask.device.{id}というAmazon Common Identifier（ACI）形式で表されます。

  • SUCCESS - ターゲットデバイスがペイロードを受信しました。
  • INVALID_DEVICE - ターゲットデバイスはペイロードを処理できません。たとえば、ターゲットデバイスがデータストアをサポートしていません。
  • DEVICE_UNAVAILABLE - デバイスがオフラインのため、ディスパッチに失敗しました。コマンド操作にattemptDeliveryUntilプロパティが設定されている場合、Alexaは、デバイスがオンラインに戻ったときにコマンドの再配信を試みます。クエリ操作を使用すると、試行された配信のステータスを取得できます。
  • DEVICE_PERMANENTLY_UNAVAILABLE - デバイスが利用不可能になっているため、ディスパッチに失敗しました。たとえば、このエラーは、ターゲットデバイスの登録が解除されている場合に発生します。
  • CONCURRENCY_ERROR - 同じデータストアリージョンを同時に更新する複数の試みがありました。新しいコマンドリクエストを送信する前に、クエリ操作を使用して、試行された配信のステータスを取得できます。
  • INTERNAL_ERROR - 不明なエラーが原因でディスパッチに失敗しました。
  • PENDING_REQUEST_COUNT_EXCEEDS_LIMIT - 保留中のリクエストの数が上限を超えています。

文字列

results[].message

（オプション）エラーを説明するメッセージです。

文字列

queuedResultId

（オプション）1つ以上のデバイスがオフライン（DEVICE_UNAVAILABLE）だった場合に適用されます。この識別子をクエリ操作で使用すると、コマンドの再配信を試みた結果のステータスを確認できます。この結果は、リクエストで指定されたattemptDeliveryUntilの時刻の少なくとも1時間後まで照会できます。

リクエスト内のデバイスがいずれもオフラインでなかった場合は提供されません。

文字列

HTTPステータスコード

操作からHTTP 200 OK以外のステータスが返された場合は、Alexaがデバイスの更新を試みる前に処理が停止したことを示します。

ステータス 説明

200 OK

データストアAPIはリクエストを解析して検証し、指定されたターゲットへのペイロードの配信を試みました。各デバイスの結果は、応答本文の一部としてresults配列に含まれています。この応答は、すべてのデバイスがコマンドペイロードを受信したことを意味するものではありません。応答本文を調べて、デバイスごとの結果を確認してください。results配列の詳細については、応答本文のプロパティを参照してください。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • COMMANDS_PAYLOAD_EXCEEDS_LIMIT - コマンドの合計サイズは、UTFエンコードで16KBを超えることはできません。
  • NO_TARGET_DEFINED - ターゲットデバイスが定義されていません。target.typeがDEVICESの場合に適用されます。
  • TOO_MANY_TARGETS - リクエスト内のターゲットの数が、20個のデバイス値または1個のユーザーIDという制限を超えています。
  • INVALID_REQUEST - リクエストのペイロードがJSONスキーマに準拠していないか、コマンドがフィールド制限に違反しています。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_ACCESS_TOKEN - アクセストークンが有効期限切れまたは無効です。

403 Forbidden

認可トークンは有効ですが、リクエストされた操作が許可されていないことを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • DATA_STORE_SUPPORT_REQUIRED - スキルにAlexa.DataStoreインターフェースのサポートが設定されていません。
    必要なインターフェースをサポートするようにスキルをアップデートしてください。詳細については、ウィジェット用のインターフェースを有効にするを参照してください。

429 Too many requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用してください。

500

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用してください。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • DATASTORE_UNAVAILABLE - 予期しない内部サービスエラーが発生しました。

キュー内の結果のクエリ

オフラインデバイスに対するコマンドのステータスを取得します。

リクエスト

オフラインデバイスに対するコマンドのステータスを取得するには、/v1/datastore/queueリソースに対してGETリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

GET /v1/datastore/queue/<queuedResultId>?maxResults={maxResults}&nextToken={nextToken}
Content-Type: application/json
Authorization: Bearer {access_token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

queuedResultId

パス

キュー内にあるオフラインデバイスへの配信を照会するための一意の識別子です。この識別子は、コマンド操作への応答から取得します。

文字列

◯

maxResults

クエリ

応答で返される結果の最大数を指定します。
有効な値は 1～100です。デフォルト値は 20です。

整数

×

nextToken

クエリ

次に取得するデータのセットを識別します。前回の応答で返されたpaginationContext.nextTokenプロパティを使用します。ページ分割された応答の反復処理を行う場合に含めます。指定しない場合、応答には結果の最初のページが返されます。

文字列

×

access_token

ヘッダー

スキルのアクセストークンです。アクセストークンを取得するには、クライアント認証情報とスコープを使用します。詳細については、認証を参照してください。

文字列

◯

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のプロパティ

リクエストの本文はありません。

応答

正常に完了すると、HTTP 200 OKと共に、キュー内にあるコマンドの結果のリストが返されます。応答が空の場合、すべてのターゲットデバイスがコマンドを受信したことを意味します。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

{
  "items": [
    {
        "deviceId": "amzn1.ask.device.2",
        "type": "DEVICE_UNAVAILABLE",
        "message": "AOGS: Send directive failure: Device unreachable"
    },
    {
        "deviceId": "amzn1.ask.device.3",
        "type": "DEVICE_UNAVAILABLE",
        "message": "AOGS: Send directive failure: Device unreachable"
    }
  ],  
  "paginationContext": {
     "totalCount": 227,
     "nextToken": "someToken.13",
     "previousToken": "someToken.1"
   }
}

応答本文のプロパティ

プロパティ 説明 型

items

ディスパッチ結果の順序不同のリストです。操作が成功しなかった以前のcommandsリクエストからの結果が含まれます。これには、typeがSUCCESSにならなかったすべての結果が該当します。

オブジェクトの配列

items[].deviceId

Alexaで更新できなかったデバイスのIDです。
amzn1.ask.device.{id}というAmazon Common Identifier（ACI）形式で表されます。

文字列

items[].type

デバイスを更新しようとした結果を示します。
有効な値は次のとおりです。

  • DEVICE_UNAVAILABLE - Alexaは、現在時刻がattemptDeliveryUntilの時刻を超えるまで、引き続きデバイスへのコマンドの配信を試みます。
  • DEVICE_PERMANENTLY_UNAVAILABLE - このデバイスへの配信試行は停止しました。スキルは、このデバイスに更新をプッシュする試みを停止する必要があります。
  • CONCURRENCY_ERROR - 同じデータストアリージョンを同時に更新する複数の試みがありました。

文字列

items[].message

エラーを説明するメッセージです。

文字列

paginationContext

（オプション）返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.totalCount

現在の応答時点での結果の合計数です。

整数

paginationContext.previousToken

結果の前のページのトークンです。結果の最初のページを返すリクエストでは提供されません。

文字列

paginationContext.nextToken

応答が分割された場合に含まれます。この値を後続のリクエストで使用します。結果の最後のページを返すリクエストでは提供されません。

文字列

HTTPステータスコード

ステータス 説明

200 OK

応答本文のitems配列に結果が含まれています。詳細については、応答本文のプロパティを参照してください。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_REQUEST - リクエストのペイロードがJSONスキーマに準拠していないか、コマンドがフィールド制限に違反しています。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • INVALID_ACCESS_TOKEN - アクセストークンが有効期限切れまたは無効です。

403 Forbidden

認可トークンは有効ですが、リクエストされた操作が許可されていないことを示します。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • DATA_STORE_SUPPORT_REQUIRED - スキルにAlexa.DataStoreインターフェースのサポートが設定されていません。
    必要なインターフェースをサポートするようにスキルをアップデートしてください。詳細については、ウィジェット用のインターフェースを有効にするを参照してください。

429 Too many requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用してください。

500

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用してください。

応答には、以下のいずれかのエラータイプとメッセージが含まれる場合があります。

  • DATASTORE_UNAVAILABLE - 予期しない内部サービスエラーが発生しました。

オブジェクトの定義

データストアAPIでは、以下のオブジェクトが定義されています。

データストアコマンド

以下のデータストアコマンドを使用すると、指定したデバイスの指定した名前空間でデータを追加または削除できます。これらのコマンドを実行するには、コマンド操作を呼び出します。

PUT_NAMESPACE

namespaceで指定した名前を使用して、リージョンに新しい名前空間を作成します。リージョンに既にnamespaceが存在する場合は無視されます。

プロパティ 説明 型 必須

type

実行するコマンドのタイプです。PUT_NAMESPACEに設定します。

文字列

◯

namespace

作成する名前空間の識別子です。スキルのリージョン内で一意である必要があります。名前空間は、次の要件を満たす空でない文字列にする必要があります。

  • 512バイト未満
  • 先頭の文字列が「sqlite_」でない
  • SQLiteの予約済みキーワードのいずれにも一致しない
  • 先頭がアンダースコア（_）でない
  • 使用できる文字セット：[_ - . a-z A-Z 0-9]

namespaceの名前は、スキルに割り当てられたデータストアストレージのサイズにカウントされます。制限の詳細については、データストアの制限を参照してください。

文字列

◯

PUT_OBJECT

指定されたnamespace内の指定されたkeyに、contentで提供されるオブジェクトを作成または更新します。指定されたnamespaceがリージョンに存在しない場合、このコマンドは名前空間を作成します。

指定されたkeyに既にオブジェクトが含まれている場合、PUT_OBJECTコマンドは既存のオブジェクトを上書きします。指定されたkeyに既に配列が含まれている場合、PUT_OBJECTコマンドは、コマンドに渡された配列でデータストア内の配列を置き換えます。このコマンドは2つの配列をマージしません。

プロパティ 説明 型 必須

type

実行するコマンドのタイプです。PUT_OBJECTに設定します。

文字列

◯

namespace

指定したcontentで更新する名前空間の一意の識別子です。スキルのリージョン内で一意である必要があります。名前空間は、次の要件を満たす空でない文字列にする必要があります。

  • 512バイト未満
  • 先頭の文字列が「sqlite_」でない
  • SQLiteの予約済みキーワードのいずれにも一致しない
  • 先頭がアンダースコア（_）でない
  • 使用できる文字セット：[_ - . a-z A-Z 0-9]

namespaceの名前は、スキルに割り当てられたデータストアストレージのサイズにカウントされます。制限の詳細については、データストアの制限を参照してください。

文字列

◯

key

指定したcontentで更新するオブジェクトの一意の識別子です。キーは、次の要件を満たす空でない文字列にする必要があります。

  • 512バイト未満
  • 先頭がアンダースコア（_）でない
  • 使用できる文字セット：[_ - . a-z A-Z 0-9]

keyの名前は、スキルに割り当てられたデータストアストレージのサイズにカウントされます。制限の詳細については、データストアの制限を参照してください。

文字列

◯

content

指定したnamespaceのkeyに作成または更新するコンテンツです。PUT_OBJECTコマンドは、このペイロードの検査や検証は行いません。

このプロパティで提供するデータが、指定したnamespaceのkeyに定義されているdataTypeと一致することを確認してください。たとえば、データストア拡張機能の設定で、指定したnamespaceのkeyにARRAYを格納するように構成している場合、PUT_OBJECTコマンドのcontentプロパティにはARRAYを渡す必要があります。例については、例：データソース内のオブジェクトを更新すると例： データストア内の配列を更新するを参照してください。

ObjectまたはArray

◯

例：データストア内のオブジェクトを更新する

以下の例では、APLドキュメントでデータストアを設定して、mainPageというキーにオブジェクトを格納するように構成します。dataTypeはOBJECTです。ドキュメントでのデータストアの設定の詳細については、APLデータストア拡張機能を参照してください。

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "uri": "alexaext:datastore:10",
      "name": "DataStore"
    }
  ],
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "objectDataStoreExample",
          "key": "mainPage",
          "dataBindingName": "dsMainPage",
          "dataType": "OBJECT"
        }
      ]
    }
  },
  "mainTemplate": {}
}

mainPageキーのオブジェクトを更新するには、以下のPUT_OBJECTコマンドを使用します。このキーに格納されるデータのdataTypeはOBJECTであるため、コマンドのcontentプロパティにはオブジェクトを指定する必要があります。この例では、mainPageキーの新しいオブジェクトに4つのプロパティが含まれています。

クリップボードにコピーされました。

{
  "type": "PUT_OBJECT",
  "namespace": "objectDataStoreExample",
  "key": "mainPage",
  "content": {
    "headerTitle": "これはデータストア内のヘッダータイトルです",
    "primaryText": "これはデータストア内の第1テキストです",
    "secondaryText": "データストア内の第2テキスト",
    "tertiaryText": "データストア内の第3テキスト"
  }
}
例： データストア内の配列を更新する

以下の例では、APLドキュメントでデータストアを設定して、mainListというキーに配列を格納するように構成します。dataTypeはARRAYです。ドキュメントでのデータストアの設定の詳細については、APLデータストア拡張機能を参照してください。

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "uri": "alexaext:datastore:10",
      "name": "DataStore"
    }
  ],
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "arrayDataStoreExample",
          "key": "mainList",
          "dataBindingName": "dsListItemsToShow",
          "dataType": "ARRAY"
        }
      ]
    }
  },
  "mainTemplate": {}
}

mainListキーの配列を更新するには、以下のPUT_OBJECTコマンドを使用します。このキーに格納されるデータのdataTypeはARRAYであるため、コマンドのcontentプロパティには配列を指定する必要があります。この例では、mainListキーの新しい配列に4つの項目が含まれています。

クリップボードにコピーされました。

{
  "type": "PUT_OBJECT",
  "namespace": "arrayDataStoreExample",
  "key": "mainList",
  "content": [
    {
      "primaryText": "1番目のリスト項目です。"
    },
    {
      "primaryText": "2番目のリスト項目です。"
    },
    {
      "primaryText": "3番目のリスト項目です。"
    },
    {
      "primaryText": "4番目のリスト項目です。"
    }
  ]
}

REMOVE_NAMESPACE

指定されたnamespaceをリージョンから削除します。指定されたnamespaceが存在しない場合は無視されます。

プロパティ 説明 型 必須

type

実行するコマンドのタイプです。REMOVE_NAMESPACEに設定します。

文字列

◯

namespace

削除する名前空間の識別子です。

文字列

◯

REMOVE_OBJECT

指定されたnamespaceのkeyに格納されているオブジェクトを削除します。オブジェクトが存在しない場合は無視されます。

プロパティ 説明 型 必須

type

実行するコマンドのタイプです。REMOVE_OBJECTに設定します。

文字列

◯

namespace

削除するオブジェクトが含まれている名前空間の一意の識別子です。スキルのリージョン内で一意である必要があります。名前空間は、次の要件を満たす空でない文字列にする必要があります。

  • 512バイト未満
  • 先頭の文字列が「sqlite_」でない
  • SQLiteの予約済みキーワードのいずれにも一致しない
  • 先頭がアンダースコア（_）でない
  • 使用できる文字セット：[_ - . a-z A-Z 0-9]

namespaceの名前は、スキルに割り当てられたデータストアストレージのサイズにカウントされます。制限の詳細については、データストアの制限を参照してください。

文字列

◯

key

削除するオブジェクトの一意の識別子です。キーは、次の要件を満たす空でない文字列にする必要があります。

  • 512バイト未満
  • 先頭がアンダースコア（_）でない
  • 使用できる文字セット：[_ - . a-z A-Z 0-9]

keyの名前は、スキルに割り当てられたデータストアストレージのサイズにカウントされます。制限の詳細については、データストアの制限を参照してください。

文字列

◯

CLEAR

スキルのリージョンを削除します。デバイス上にスキルのリージョンがない場合は無視されます。

リージョンを削除すると、そのリージョンに格納されている名前空間とオブジェクトがすべて削除されます。リージョン内のデータは復元できません。次回PUT_NAMESPACEコマンドまたはPUT_OBJECTコマンドを実行すると、それらのコマンドに指定されたデータでリージョンが再作成されますが、削除されたデータは一切復元されません。

プロパティ 説明 型 必須

type

実行するコマンドのタイプです。CLEARに設定します。

文字列

◯

Errorオブジェクト

Errorオブジェクトは、エラーが発生したときに応答に含まれるエラーのタイプとメッセージを定義します。

以下は、応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
プロパティ 説明 型

type

発生したエラーのタイプです。
具体的なエラータイプについては、各操作のHTTPステータスコードの表を参照してください。

文字列

message

人が判読できる形式のエラーメッセージです。このエラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックは構築しないでください。

文字列

Targetオブジェクト

Targetオブジェクトは、デバイスIDの値のリストか、単一のユーザーIDのいずれかを表します。このターゲットをcommands操作で使用します。次の一覧は、デバイスに更新を発行するための基準を示しています。

  • 単一のデバイスまたは複数のデバイスのグループに更新を発行するには、ターゲットのtypeとしてDEVICESを設定し、最大20個のデバイスIDの配列をitemsプロパティに指定します。指定したコマンドが、指定した各デバイスで実行されます。
  • 特定のユーザーに関連付けられたデバイスに更新を発行するには、ターゲットのtypeとしてUSERを指定し、単一のユーザーIDをitemプロパティに指定します。指定したコマンドが、そのユーザーに関連付けられた各デバイスで実行されます。この操作では、データストアをサポートしていないデバイスはすべてスキップされます。

スキルに送信されるすべてのリクエストには、context.System.user.userIdプロパティとcontext.System.device.deviceIdプロパティに、deviceIdとuserIdのプロパティが含まれています。これらの値はUsagesInstalledリクエストから取得できます。このリクエストは、ユーザーがウィジェットをインストールし、データストアREST APIで使用する永続ストレージに値を保存したときにスキルに送信されます。これらの値はスキルに固有です。あるスキルのdeviceIdまたはuserIdを別のスキルで使用することはできません。スキルリクエスト内のユーザーIDとデバイスIDの詳細については、Systemオブジェクトを参照してください。

プロパティ 説明 型 必須

target.type

コマンドのターゲットのタイプです。
有効な値は DEVICESまたはUSERです。

列挙値

◯

target.items

更新するデバイスを表すデバイスIDのリストです。以前のUsagesInstalledリクエストから返された1つ以上のcontext.System.device.deviceId値を設定します。
操作により、指定した各デバイスに対してコマンドが実行されます。typeがDEVICESの場合に指定します。
最大サイズは 20です。

文字列の配列

typeがDEVICESの場合は◯

target.id

ユーザーIDです。UsagesInstalledリクエストから返されたcontext.System.user.userIdを設定します。
操作により、このユーザーに関連付けられた各デバイスに対してコマンドが実行されます。typeがUSERの場合に指定します。

文字列

typeがUSERの場合は◯

サンプルコード

次のサンプルコードは、基本的なウィジェットを作成し、データストアAPIを使用してデバイス上のデータストアを更新する方法を示します。

このページは役に立ちましたか？

最終更新日: 2025 年 12 月 17 日