APL Extensions

Extensionsは、APLランタイムに追加のデータソース、コマンド、イベントハンドラーを提供するオプションの拡張機能です。Extensionsは、APLに追加機能を提供しますが、一部のデバイスでは利用できないものもあります。

利用可能なextensions：

extensionをリクエストする

APLドキュメントでextensionを使用する前に、スキルでextensionをリクエストする必要があります。一部のextensionsでは、次の2つの手順を実行する必要があります。

スキルマニフェストでextensionをリクエストします。
APLドキュメントでextensionをリクエストします。

マニフェストに含める必要があるのは一部のextensionsです。extension固有の要件については、extensionのドキュメントを参照してください。

スキルマニフェストでextensionをリクエストする

一部のextensionsは、スキルマニフェストでextensionを宣言してから使用する必要があります。また、一部のextensionsには、マニフェストで有効または無効にできるデフォルトの動作があります。

ALEXA_EXTENSIONインターフェースのapis.custom.interfacesのマニフェストでextensionsを宣言します。ALEXA_EXTENSIONインターフェースには、次のプロパティがあります。

名前型説明

名前	型	説明
`type`	文字列	`ALEXA_EXTENSION`にする必要があります。
`requestedExtensions`	オブジェクトの配列	APLドキュメントで使用するextensionsの配列が含まれます。配列の各オブジェクトには、有効にするextensionのURIが設定された`uri`プロパティがあります。extensionでは`uri`が定義されています。たとえば、Smart Motion extensionの場合、URIは`alexaext:smartmotion:10`です。 extensionの`uri`と`requestedExtensions`プロパティでextensionをリクエストする必要があるかどうかを判断するには、extensionのドキュメントを参照してください。
`autoInitializedExtensions`	オブジェクトの配列	デフォルトの動作にコンフィギュレーションを行うことができるextensionsの配列が含まれます。これにより、extensionsが「コード不要」の動作をサポートしている場合は、コード不要の動作を有効にできます。各オブジェクトには、次の2つのプロパティがあります。 `uri` - コンフィギュレーションを行うextensionのURI。デフォルト設定をサポートするextensionのURIを指定する必要があります。 `settings` - スキルマニフェストでコンフィギュレーションを行うことができる各extension設定のキーと値のペアのセット。たとえば、Smart Motion extensionの場合、`autoInitializedExtensions`でデフォルトの`wakeWordResponse`を設定できます。これで、指定された設定がスキルで使用されます。APLドキュメントのコンフィギュレーションは不要です。

type

文字列

ALEXA_EXTENSIONにする必要があります。

requestedExtensions

オブジェクトの配列

APLドキュメントで使用するextensionsの配列が含まれます。配列の各オブジェクトには、有効にするextensionのURIが設定されたuriプロパティがあります。extensionではuriが定義されています。たとえば、Smart Motion extensionの場合、URIはalexaext:smartmotion:10です。

extensionのuriとrequestedExtensionsプロパティでextensionをリクエストする必要があるかどうかを判断するには、extensionのドキュメントを参照してください。

autoInitializedExtensions

オブジェクトの配列

デフォルトの動作にコンフィギュレーションを行うことができるextensionsの配列が含まれます。これにより、extensionsが「コード不要」の動作をサポートしている場合は、コード不要の動作を有効にできます。各オブジェクトには、次の2つのプロパティがあります。

uri - コンフィギュレーションを行うextensionのURI。デフォルト設定をサポートするextensionのURIを指定する必要があります。
settings - スキルマニフェストでコンフィギュレーションを行うことができる各extension設定のキーと値のペアのセット。

たとえば、Smart Motion extensionの場合、autoInitializedExtensionsでデフォルトのwakeWordResponseを設定できます。これで、指定された設定がスキルで使用されます。APLドキュメントのコンフィギュレーションは不要です。

次の例は、Smart MotionとEntity Sensingというextensionsに対応するコンフィギュレーションを行ったマニフェストを示しています。この例では、Smart Motion extensionはデフォルトのウェイクワード応答としてturnToWakeWordを使用します。

{
  "apis": {
    "custom": {
      "interfaces": [
        {
          "type": "ALEXA_EXTENSION",
          "requestedExtensions": [
            {
              "uri": "alexaext:smartmotion:10"
            },
            {
              "uri": "alexaext:entitysensing:10"
            }
          ],
          "autoInitializedExtensions": [
            {
              "uri": "alexaext:smartmotion:10",
              "settings": {
                "wakeWordResponse": "turnToWakeWord"
              }
            }
          ]
        }
      ]
    }
  }
}

extensionに対して行えるコンフィギュレーションの詳細については、当該extensionのドキュメントを参照してください。Smart Motion extensionには、スキルマニフェストでコンフィギュレーションを行える設定があります。

APLドキュメントでextensionをリクエストする

extensionでコマンド、プロパティ、イベントハンドラーを使用するには、APLドキュメントまたはインポートしたAPLパッケージでextensionを明示的にリクエストする必要があります。次に、ドキュメントでextensionを使用する前に、デバイスでextensionがサポートされているかどうかを確認します。

extensionsのセットをリクエストして、extensionsプロパティに読み込みます。extensionsプロパティには、オブジェクトのリストが含まれています。各オブジェクトには、extensionsの参照に使用するnameプロパティとextensionのuriが含まれます。extensionは独自のuriを定義します。extensionの参照時に使う文字列値に、nameを設定します。

たとえば、現在の天気情報を読み取るextensionのURIが"aplext:weather_info_deluxe:v10"の場合、次のようになります。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Weather",
      "uri": "aplext:weather_info_deluxe:v10"
    }
  ]
}

APLドキュメントは、${environment.extension.Weather}を読み取ることで、ユーザーのデバイスに天気のextensionが存在するかどうかをチェックできます。

各extensionのuriは一意です。URIはextensionによって定義され、extensionと共にドキュメント化されます。たとえば、Backstack extensionは、"aplext:backstack:10"というuriを使用します。

APLは、ドキュメントおよび関連のパッケージにリクエストされたすべてのextensionsを読み込もうとします。2つの異なる名前で同じextensionを読み込むことは可能です。どちらの名前でも、extensionコマンドの送信とextensionイベントハンドラーの登録に使用できます。同じ1つの名前で2つの異なるextensionsをリクエストするとエラーとなり、ドキュメントを読み込めません。

データバインディングコンテキストでのextensionsプロパティは、リクエストおよび読み込まれたextensionsの状態を示します。

ドキュメントでextensionをリクエストする方法については、ドキュメントのextensionsプロパティを参照してください。extensionのグローバルプロパティを取得する方法については、environment.extensionsプロパティを参照してください。

extensionの設定

ドキュメントのsettingsプロパティには、リクエストされたextensionの設定情報が含まれます。リクエストされたextensionは、extensionのエイリアス名を使って設定情報を取得します。APLは、ドキュメントを処理して表示する前にextensionを読み込むため、settingsプロパティがデータバインディングにアクセスすることはできません。

たとえば、カスタマイズされたメトリックのログ作成が可能なランタイムextensionを考えてみましょう。メトリックログのextensionは、settingsを使って、次のようにクライアントのコア情報を設定できます。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "ManyMetrics",
      "uri": "aplext:many_metrics.somebigcompanyname.com:1.2"
    }
  ],
  "settings": {
    "ManyMetrics": {
      "applicationName": "MyMovieSearcher",
      "applicationCategory": "Entertainment",
      "applicationAuthor": "Generic Movie Corp"
    }
  }
}

上の例では、ドキュメントが"ManyMetrics"というエイリアス名でextensionをリクエストしています。ランタイムは、そのextensionの存在をチェックし、存在した場合はそのextensionに"settings.ManyMetrics"オブジェクトを渡します。

別々のエイリアスを使って1つのドキュメントから複数回、1つのextensionがリクエストされる場合があります。このような状況は、ドキュメントのextensionsプロパティに同じextensionが複数回リストされている場合、または別々のパッケージから同じextensionがリクエストされる場合に発生する可能性があります。各エイリアスは、"environment.extension"環境プロパティで表されます。特定のextensionは1回しか読み込めないため、extensionが読み込まれる前にすべてのsettingsがマージされます。settingsはパッケージ順にマージされるため、後のパッケージ（およびドキュメント）が前のパッケージで定義された設定を上書きします。

設定のマージエラーの特定は難しい場合があるため、settingsプロパティを持つextensionsは1つのパッケージのみ、またはメインのドキュメントのみでリクエストするようにしてください。

extensionのコマンド

「extension」コマンドは、登録済みのextensionで定義されたカスタムコマンドです。extensionコマンドは、すべての基本コマンドプロパティを継承するため、type、description、delay、screenLock、sequencer、whenを自動でサポートします。登録済みextensionが、extensionコマンド内に必須または任意のプロパティを追加で指定することもできます。

extensionコマンドは、通常のコマンドと同じように呼び出されます。コマンドのtypeには、"EXTENSION_NAME:COMMAND_NAME"を設定します。EXTENSION_NAMEはextensionをリクエストする際に使用したnameプロパティ、COMMAND_NAMEはextensionが定義したコマンド名です。つまり、extensionをリクエストする際に定義したnameプロパティを、extensionコマンドを呼び出す際のnamespaceとして使用します。

たとえば、FishFeeder extension（URI="aplext:fishfeeder:10"）を登録した、APL対応の水槽があるとします。このextensionは、「Feed」というカスタムコマンドを提供します。このコマンドでは、"amount"プロパティに1～100の数値（魚のエサのグラム数）を設定する必要があります。以下は、APLドキュメントでこのコマンドを使う例です。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Fish",
      "uri": "aplext:fishfeeder:10"
    }
  ],
  "mainTemplate": {
    "items": [
      {
        "when": "${environment.extension.Fish}",
        "type": "Container",
        "data": [
          10,
          25,
          100
        ],
        "items": {
          "type": "TouchWrapper",
          "items": {
            "type": "Text",
            "text": "魚に${data}グラム、エサをあげて"
          },
          "onPress": {
            "type": "Fish:Feed",
            "amount": "${data}"
          }
        }
      },
      {
        "description": "FishFeeder extensionがない場合のフォールバック",
        "type": "Text",
        "text": "FishFeederがありません"
      }
    ]
  }
}

上の例では、"aplext:fishfeeder:10" extensionをリクエストしています。extensionがインストールされている場合は3つのボタンのリストが作成され、インストールされていない場合は警告メッセージが表示されます。各ボタンがFeedカスタムイベントを生成し、与えるエサの量を指定します。

Extensionイベントハンドラー

APL Extensionsは、ドキュメントにカスタムイベントを送信できます。extensionイベントハンドラーは、これらのカスタムイベントをドキュメント内で受け取ります。各APL Extensionで定義できるカスタムイベントの数に制限はありません。イベント名、および通常または高速モードで呼び出されたかどうかを確認するには、extensionのドキュメントを参照してください。

イベントハンドラーで受け取るイベントの形式は次のとおりです。

"event": {
  "source": {
    "type": "Document",
    "handler": NAME,   // ハンドラーの名前   
    "id": null,        // 値は報告されません  
    "uid": null,       // 値は報告されません  
    "value": null      // 値は報告されません  
  }
}

extensionイベントハンドラーが、"event"プロパティと同じレベルで追加のプロパティを報告する場合があります。例として、ワイヤレスのハードウェアボタンをサポートする"aplext:remotebutton:13"というextensionを考えてみましょう。ボタンが押されると、extensionは"buttonName"および"buttonColor"というプロパティを含む"OnPress"イベントを送信します（ここでは、ボタンには名前があり、ランダムに色が変わると仮定します）。このイベントによって生成されるデータバインディングコンテキストは次のとおりです。

{
  "buttonName": "BigRedButton",  //またはボタンから渡された任意の値
  "buttonColor": "red",   //またはボタンから渡された任意の色
  "event": {
    "source": {
      "type": "Document",
      "handler": "OnPress",
      "id": null,        // 値は報告されません  
      "uid": null,       // 値は報告されません  
      "value": null      // 値は報告されません  
    },
  }
}

ドキュメントの最上位レベルにある名前を指定されたイベントハンドラーが、extensionイベントを受け取ります。イベントハンドラーの名前は"EXTENSION_NAME:EVENT_NAME"です。EXTENSION_NAMEはextensionを読み込む際に使用したnameプロパティ、EVENT_NAMEはextensionが定義したイベント名です。次に例を示します。

{ "type": "APL", "version": "1.4", "extensions": [ { "name": "Button", "uri": "aplext:remotebutton:13" } ], "mainTemplate": { "items": { "type": "Text", "id": "MyTextBox", "text": "${environment.extension.Button ? '押されたボタンはありません' : 'ボタンを買いましょう！'}", "color": "gray" } }, "Button:OnPress": [ { "type": "SetValue", "componentId": "MyTextBox", "property": "text", "value": "${buttonName}が押されました" }, { "type": "SetValue", "componentId": "MyTextBox", "property": "color", "value": "${buttonColor}" } ] }

上の例では、"aplext:remotebutton13"ハンドラーに"Button"というnameが割り当てられています。extensionが"OnPress"というイベントを送信するため、ドキュメントレベルのイベントハンドラーは"Button:OnPress"となります。

Extensionのライブデータ

APL Extensionsは、ドキュメントのグローバルデータバインディングコンテキストに、カスタムの「ライブ」データオブジェクトを追加できます。ドキュメント読み込み時のextensionの静的な状態のみを報告するenvironment.extension環境プロパティと異なり、これらの「ライブ」データオブジェクトは、ドキュメントのライフサイクルを通じ、extensionのユースケースに応じて変化します。各APL extensionが定義できるカスタムライブデータオブジェクトの数に制限はありません。

extensionによって実装されるライブデータオブジェクトは、extensionのsettingsプロパティを通じてドキュメントに公開され、グローバルデータバインディングコンテキストのデータオブジェクトにドキュメントの意図するnameを示す必要があります。

ドキュメントが、extensionで利用可能なライブデータオブジェクトに対して有効なsettingsプロパティを提供しない場合、これらのオブジェクトをデータバインディングコンテキストに追加しないでください。

関連のsettingsプロパティ、形式、extensionによって提供されるライブデータの用途については、extensionのドキュメントを参照してください。

たとえば、FishFeeder extension（URI="aplext:fishfeeder:10"）を登録した、APL対応の水槽があるとします。FishFeeder extensionは、ドキュメントのデータバインディングコンテキストに、次の形式でライブデータオブジェクトを提供します。

{
  "rayFinnedFish":[],
  "lobeFinnedFish":[],
  "lampreys":[]
}

extensionは、ドキュメントがデータバインディングで使用できるライブデータオブジェクトの名前を定義した設定プロパティも、提供する必要があります。以下は、extensionがデータオブジェクトをドキュメント化する方法例です。

名前	型	デフォルト	説明
`fishTypeDataName`	文字列	null	`fishType`ライブデータオブジェクトをデータバインディングコンテキストに追加する際に使用する名前です。

これにより、APLドキュメントから、上で定義したようにextensionのfishTypeDataName settingsプロパティの値を指定して、extensionのライブデータオブジェクトにアクセスできるようになります。

{
  "type": "APL",
  "version": "1.4",
  "extensions": [
    {
      "name": "Fish",
      "uri": "aplext:fishfeeder:10"
    }
  ],
  "settings": {
    "Fish": {
      "fishTypeDataName": "fishType"
    }
  },
  "mainTemplate": {
    "items": [
      {
        "when": "${environment.extension.Fish}",
        "type": "Container",
        "items": [
          {
            "type": "Text",
            "text": "現在、水槽には${fishType.rayFinnedFish.length}の条鰭類がいます。"
          }
        ]
      },
      {
        "description": "FishFeeder extensionがない場合のフォールバック",
        "type": "Text",
        "text": "FishFeederがありません"
      }
    ]
  }
}

上の例では、データバインディングname "fishType"が、"aplext:fishfeeder:10" extensionでライブデータオブジェクトに定義されています。extensionは、ライブデータオブジェクトfishTypeを、"fishType"としてグローバルデータバインディングコンテキストに追加します。