Alexa.DataStore.PackageManagerインターフェースリファレンス

Alexa.DataStore.PackageManagerインターフェースリファレンス

Alexa.DataStore.PackageManagerインターフェースは、Alexaがデバイス上のAPLパッケージをインストール、削除、更新した場合にスキルに通知するリクエストを提供します。APLパッケージは、ウィジェットなど、特定のViewportでAPLエクスペリエンスをレンダリングするために使用される、APLドキュメントと関連アセットの自己完結型リソースです。

デバイス上のAPLパッケージを管理するには、Alexa.DataStore.PackageManagerインターフェースを使用します。

APLパッケージ形式の詳細については、APLパッケージリファレンスを参照してください。

Alexa.DataStore.PackageManagerインターフェースを有効にする

Alexa.DataStore.PackageManagerインターフェースを使用するには、スキルでこのインターフェースを有効にする必要があります。開発者コンソールまたはASK CLIを使用して、このインターフェースに対応するようにスキルを更新できます。

開発者コンソールでインターフェースを設定する

  1. 開発者コンソールにサインインして、設定するスキルの名前をクリックします。
  2. ビルド＞インターフェースページに移動します。
  3. データストアパッケージオプションを有効にします。
  4. インターフェースを保存、モデルをビルドの順にクリックして、対話モデルを再ビルドします。

ASK CLIでインターフェースを設定する

ALEXA_DATASTORE_PACKAGEMANAGERをmanifest.apis.custom.interfaces配列のスキルマニフェストに追加します。インターフェースを有効にするときに、スキルの各パッケージのidも指定します。各パッケージは1つのウィジェットに相当します。

以下の例は、配列内のスキルマニフェストでインターフェースを有効にする方法を示しています。

{
  "manifest": {
    "apis": {
      "custom": {
        "endpoint": {},
        "interfaces": [
          {
            "type": "ALEXA_DATASTORE_PACKAGEMANAGER",
            "packages": [
              {
                "id": "MyWidget1"
              },
              {
                "id": "MyWidget2"
              }
            ]
          }
        ],
        "regions": {}
      }
    },
    "manifestVersion": "1.0",
    "privacyAndCompliance": {},
    "publishingInformation": {}
  }
}

リクエスト

以下の表に、Alexa.DataStore.PackageManagerインターフェースで使用できるリクエストを示します。

リクエスト 説明

UsagesInstalled

Alexaがユーザーのデバイスにパッケージをインストールしたときにスキルに送信されます。このリクエストは、パッケージマニフェストでinstallStateChangesがINFORMに設定されている場合に適用されます。

UsagesRemoved

ユーザーがデバイスからウィジェットを削除することを選択し、Alexaがパッケージをアンインストールしたときにスキルに送信されます。

UpdateRequest

Alexaがユーザーのデバイス上のパッケージを新しいバージョンに更新したときにスキルに送信されます。このリクエストは、パッケージマニフェストでupdateStateChangesがINFORMに設定されている場合に適用されます。

InstallationError

パッケージのインストール、削除、更新中に発生したエラーについてスキルに通知するために送信されます。

UsagesInstalledリクエスト

Alexaがユーザーのデバイスにパッケージをインストールし、そのパッケージのinstallStateChangesがINFORMに設定されている場合に、スキルがUsagesInstalledリクエストを受け取ります。installStateChangesプロパティがAUTOMATICに設定されている場合、Alexaはこのリクエストを送信しません。

このリクエストは、ウィジェットに表示する初期データで、デバイス上のデータストアを更新する場合に使用します。データストアの更新にはデータストアREST APIを使用します。詳細については、データストアREST APIリファレンスを参照してください。

以下は、UsagesInstalledリクエストの例です。

{
  "type": "Alexa.DataStore.PackageManager.UsagesInstalled",
  "payload": {
    "packageId": "WeatherWidget",
    "packageVersion": "1.0.0",
    "usages": [
      {
        "instanceId": "amzn1.ask.package.v1.instance.v1.{uuid}",
        "location": "FAVORITE"
      }
    ]
  }
}

UsagesInstalledプロパティ

UsagesInstalledリクエストのプロパティを以下の表に示します。

プロパティ 型 必須 説明

type

文字列

◯

リクエストのタイプです。常にAlexa.DataStore.PackageManager.UsagesInstalledです。

payload.packageId

文字列

◯

デバイスにインストールされたパッケージのパッケージIDです。

payload.packageVersion

文字列

◯

デバイスにインストールされたパッケージのバージョンです。

payload.usages

オブジェクトの配列

◯

パッケージの使用状況の配列です。

payload.usages[].instanceId

文字列

×

デバイスにインストールされているパッケージインスタンスのIDです。

payload.usages[].location

文字列

◯

パッケージがデバイス上のどこにインストールされているかを示す列挙値です。
指定できる値： FAVORITE

有効な応答

スキルは、UsagesInstalledリクエストに標準的な応答で応答できます。

UsagesRemovedリクエスト

ユーザーがデバイスからウィジェットを削除することを選択し、Alexaがパッケージをアンインストールした場合に、スキルがUsagesRemovedリクエストを受け取ります。

このリクエストを使用して、デバイスのデータストアからデータを消去します。データストアの更新にはデータストアREST APIを使用します。詳細については、データストアREST APIリファレンスを参照してください。

以下は、UsagesRemovedリクエストの例です。

{
  "type": "Alexa.DataStore.PackageManager.UsagesRemoved",
  "payload": {
    "packageId": "WeatherWidget",
    "packageVersion": "1.0.0",
    "usages": [
      {
        "instanceId": "amzn1.ask.package.v1.instance.v1.{uuid}",
        "location": "FAVORITE"
      }
    ]
  }
}

UsagesRemovedプロパティ

UsagesRemovedリクエストのプロパティを以下の表に示します。

プロパティ 型 必須 説明

type

文字列

◯

リクエストのタイプです。常にAlexa.DataStore.PackageManager.UsagesRemovedに設定します。

payload.packageId

文字列

◯

削除されたウィジェットパッケージのパッケージIDです。パッケージIDはパッケージの作成時に設定します。詳細については、ウィジェットを作成して管理するを参照してください。

payload.packageVersion

文字列

◯

削除されたパッケージのバージョンです。

payload.usages

オブジェクトの配列

◯

パッケージの使用状況の配列です。

payload.usages[].instanceId

文字列

×

デバイスにインストールされているパッケージインスタンスのIDです。

payload.usages[].location

文字列

◯

パッケージがデバイス上のどこにインストールされているかを示す列挙値です。
指定できる値： FAVORITE

有効な応答

スキルは、UsagesRemovedリクエストに標準的な応答で応答できます。

UpdateRequestリクエスト

Alexaがユーザーのデバイス上のパッケージを新バージョンに更新し、そのパッケージのupdateStateChangesがINFORMに設定されている場合に、スキルがUpdateRequestリクエストを受け取ります。updateStateChangesプロパティがAUTOMATICに設定されている場合、Alexaは更新後にこのリクエストを送信しません。

パッケージマニフェストのversionの値を大きくしてパッケージの新バージョンを公開したときに、更新が行われます。Alexaは、古いバージョンのパッケージがインストールされているユーザーデバイスを判断し、そのデバイスを新しいバージョンに更新して、更新を開発者に通知するためにUpdateRequestをスキルに送信します。リクエストには、パッケージの古いバージョン番号と新しいバージョン番号が含まれています。

このリクエストは、新バージョンのウィジェットに表示するデータで、デバイス上のデータストアを更新する場合に使用します。データストアの更新にはデータストアREST APIを使用します。詳細については、データストアREST APIリファレンスを参照してください。

以下は、UpdateRequestリクエストの例です。

{
  "request": {
    "type": "Alexa.DataStore.PackageManager.UpdateRequest",
    "packageId": "WeatherWidget",
    "fromVersion": "1.0.0",
    "toVersion": "1.0.1"
  }
}

UpdateRequestプロパティ

プロパティ 型 必須 説明

type

文字列

◯

リクエストのタイプです。Alexa.DataStore.PackageManager.UpdateRequestに設定します。

packageId

文字列

◯

更新するパッケージのパッケージIDです。

fromVersion

文字列

◯

パッケージの以前のバージョンです。以前デバイスにインストールされていたパッケージのバージョンを示します。

toVersion

文字列

◯

更新後のパッケージの新しいバージョンです。

有効な応答

スキルは、UpdateRequestリクエストに標準的な応答で応答できます。

InstallationErrorリクエスト

パッケージのインストール、削除、更新中に発生したエラーについてスキルに通知するために送信されます。

以下は、InstallationErrorリクエスト通知の例です。

{
  "type": "Alexa.DataStore.PackageManager.InstallationError",
  "packageId": "WeatherWidget",
  "version": "1.0.0",
  "error": {
    "type": "PACKAGEMANAGER_INTERNAL_ERROR",
    "content": {}
  }
}

InstallationErrorプロパティ

プロパティ 型 必須 説明

type

文字列

◯

リクエストのタイプです。Alexa.DataStore.PackageManager.InstallationErrorに設定します。

packageId

文字列

◯

エラーをトリガーしたウィジェットパッケージのパッケージIDです。

version

文字列

◯

エラーをトリガーしたパッケージのバージョンです。

error

Errorオブジェクト

×

発生したエラーに関する詳細情報を含むエラーオブジェクトです。

エラータイプ

型 説明

PACKAGEMANAGER_INTERNAL_ERROR

デバイスがパッケージをインストールまたは更新しようとしたときに発生する内部エラーです。

有効な応答

スキルは、InstallationErrorリクエストに標準的な応答で応答できます。

リクエスト内のAlexa.DataStore.PackageManagerオブジェクト

スキルリクエスト内のcontext.Alexa.DataStore.PackageManagerオブジェクトは、デバイスにインストールされているパッケージに関する情報を提供します。このオブジェクトは、スキルによってインストールされたパッケージの詳細情報を提供します。

{
  "version": "1.0",
  "session": {},
  "context": {
    "AudioPlayer": {},
    "Viewports": [],
    "Alexa.Presentation.APL": {
      "presentationUri": "<文字列>"
    },
    "Alexa.DataStore.PackageManager": {
      "installedPackages": [
        {
          "packageId": "<パッケージID>",
          "packageVersion": "1.0.0"
        }
      ]
    }
  }
}
プロパティ 型 必須 説明

installedPackages

配列

◯

デバイスにインストールされているパッケージを表すオブジェクトの配列です。スキルに関連付けられたインストール済みパッケージを含みます。

installedPackages[].packageId

文字列

◯

デバイスにインストールされているパッケージのIDです。

installedPackages[].packageVersion

文字列

◯

デバイスにインストールされているパッケージのバージョンです。

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

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