APL拡張機能

Note: Sign in to the developer console to build or publish your skill.

APL拡張機能

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

利用可能な拡張機能：

拡張機能をリクエストする

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

スキルマニフェストで拡張機能をリクエストする。
APLドキュメントで拡張機能をリクエストする。

すべての拡張機能をマニフェストに含める必要があるとは限りません。拡張機能固有の要件については、各拡張機能のドキュメントを参照してください。

スキルマニフェストで拡張機能をリクエストする

一部の拡張機能は、使用する前にスキルマニフェストで拡張機能を宣言する必要があります。拡張機能によっては、デフォルトの動作をマニフェストで有効または無効にできる場合もあります。

このような拡張機能は、マニフェストのapis.custom.interfacesのALEXA_EXTENSIONインターフェースで宣言します。ALEXA_EXTENSIONインターフェースには、次のプロパティがあります。

名前型説明

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

type

文字列

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

requestedExtensions

オブジェクトの配列

APLドキュメントで使用する拡張機能の配列を指定します。配列の各オブジェクトにはuriプロパティがあり、有効にする拡張機能のURIに設定します。uriは拡張機能によって定義されます。たとえば、スマートモーション拡張機能のURIはalexaext:smartmotion:10です。

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

autoInitializedExtensions

オブジェクトの配列

デフォルトの動作を設定できる拡張機能の配列を指定します。これにより、拡張機能が「コード不要」の動作をサポートしている場合は、その動作を有効にすることができます。各オブジェクトには、次の2つのプロパティがあります。

uri - 設定する拡張機能のURIです。デフォルト設定をサポートする拡張機能のURIを指定する必要があります。
settings - スキルマニフェストで設定できる各拡張機能設定を指定する、キーと値のペアのセットです。

たとえば、スマートモーション拡張機能では、autoInitializedExtensionsでデフォルトのwakeWordResponseを設定できます。ここで指定した設定がスキルで使用され、それ以上の設定をAPLドキュメントで行う必要はありません。

次の例は、スマートモーションとEntity Sensingの各拡張機能を使用するように設定されたマニフェストを示しています。この例では、スマートモーション拡張機能のデフォルトのウェイクワード応答としてturnToWakeWordが使用されます。

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

拡張機能に構成できる設定の詳細については、その拡張機能のドキュメントを参照してください。スマートモーション拡張機能には、スキルマニフェストで構成できる設定があります。

APLドキュメントで拡張機能をリクエストする

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

読み込む一連の拡張機能をリクエストするには、extensionsプロパティを使用します。extensionsプロパティはオブジェクトのリストを受け取ります。各オブジェクトは、拡張機能を参照するために使用するnameプロパティと、拡張機能のuriで構成されます。拡張機能によって固有のuriが定義されています。nameには、拡張機能を参照するために使用する文字列値を設定します。

たとえば、現在の天気情報を読み取る拡張機能があり、そのURIが「aplext:weather_info_deluxe:v10」であるとすると、次のように設定できます。

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

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

各拡張機能には一意のuriがあります。URIは拡張機能によって定義され、拡張機能のドキュメントに記載されています。たとえば、バックスタック拡張機能では、「aplext:backstack:10」というuriが使用されます。

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

特定の拡張機能のリクエストでrequiredプロパティがtrueに設定されていると、その拡張機能が利用できない場合や登録されない場合、ドキュメントがインフレートされなくなります。これは望ましい動作ではない可能性があります。通常は、ドキュメントで拡張機能への接続に失敗しても、一部の機能を制限して引き続き使用できることが期待されます。requiredプロパティをtrueに設定するのは、ドキュメントが読み込まれない場合のフォールバックプランがある場合だけにしてください。

データバインディングコンテキスト内のextensionsプロパティは、リクエストされて読み込まれた拡張機能の状態を示します。

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

拡張機能の設定

ドキュメントのsettingsプロパティには、リクエストした拡張機能の設定情報を含めることができます。リクエストされた拡張機能は、その拡張機能のエイリアス名を使用して設定情報を取得します。APLは、ドキュメントを処理して表示する前に拡張機能を読み込みます。APLバージョン2023.3以降では、settingsでデータバインディング式がサポートされます。ただし、データバインディング式で参照できるのは、初期状態のデータバインディングコンテキストで使用できるプロパティに制限されます。environmentなど、デバイスに関する情報を取得することはできますが、データソースからのデータは取得できません。

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

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

この例では、ドキュメントは「ManyMetrics」というエイリアス名で拡張機能をリクエストしています。ランタイムは、指定された拡張機能の存在をチェックし、存在する場合はその拡張機能に「settings.ManyMetrics」オブジェクトを渡します。

1つの拡張機能が、1つのドキュメントから異なるエイリアスで複数回リクエストされる場合があります。この状況は、ドキュメントのextensionsプロパティに同じ拡張機能が複数回記述されている場合や、同じ拡張機能が複数の異なるパッケージによってリクエストされている場合に発生する可能性があります。各エイリアスは、「environment.extension」環境プロパティに含められます。1つの拡張機能は1回しか読み込むことができないため、拡張機能のすべてのsettingsは、その拡張機能が読み込まれる前にマージされます。settingsはパッケージ順にマージされるため、後のパッケージ（およびドキュメント）が前のパッケージで定義された設定をオーバーライドします。

設定のマージエラーの特定は困難を伴う可能性があるため、settingsプロパティを持つ拡張機能は、1つのパッケージまたはメインドキュメントでのみリクエストすることをお勧めします。

拡張機能のコマンド

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

拡張機能コマンドは、通常のコマンドと同じように呼び出されます。コマンドのtypeは、「EXTENSION_NAME:COMMAND_NAME」に設定する必要があります。EXTENSION_NAMEは拡張機能のリクエスト時に使用したnameプロパティ、COMMAND_NAMEは拡張機能によって定義されるコマンド名です。つまり、拡張機能をリクエストしたときに定義したnameプロパティが、拡張機能コマンドを呼び出すときのnamespaceとして使用されます。

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

{
  "type": "APL",
  "version": "2024.3",
  "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拡張機能がない場合のフォールバック",
        "type": "Text",
        "text": "FishFeederがありません"
      }
    ]
  }
}

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

拡張機能のイベントハンドラー

APL拡張機能は、ドキュメントにカスタムイベントを送信できます。これらのカスタムイベントは、ドキュメント内で拡張機能のイベントハンドラーによって受け取られます。APL拡張機能ごとに任意の数のカスタムイベントを定義できます。各イベントの名前と、それらが通常モードと高速モードのどちらで呼び出されるかを確認するには、拡張機能のドキュメントを参照してください。

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

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

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

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

ドキュメントのトップレベルにある名前付きのイベントハンドラーが、拡張機能のイベントを受け取ります。イベントハンドラーの名前は「EXTENSION_NAME:EVENT_NAME」です。EXTENSION_NAMEは拡張機能の読み込み時に使用したnameプロパティ、EVENT_NAMEは拡張機能によって定義されるイベント名です。次に例を示します。

{
  "type": "APL",
  "version": "2024.3",
  "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」のハンドラーのnameに「Button」という名前が割り当てられています。拡張機能が「OnPress」というイベントを送信するため、ドキュメントレベルのイベントハンドラーは「Button:OnPress」となります。

拡張機能のハンドラーは、ドキュメントのデータバインディングコンテキストで実行されます。

拡張機能のライブデータ

APL拡張機能は、ドキュメントのグローバルデータバインディングコンテキストにカスタムの「ライブ」データオブジェクトを追加できます。environment.extension環境プロパティで報告されるのは、ドキュメントの読み込み時点における拡張機能の静的な状態だけです。これとは異なり、「ライブ」データオブジェクトは、ドキュメントのライフサイクルを通じて、拡張機能のユースケースに応じて変更される可能性があります。APL拡張機能ごとに任意の数のカスタムライブデータオブジェクトを定義できます。

拡張機能によって実装されるライブデータオブジェクトは、拡張機能のsettingsプロパティを通じてドキュメントに公開される必要があります。ドキュメントでは、このプロパティを使用して、グローバルデータバインディングコンテキスト内のデータオブジェクトに割り当てる名前を指定します。

拡張機能から提供されるライブデータオブジェクトに対して、有効なsettingsプロパティがドキュメントに指定されていない場合、それらのオブジェクトはデータバインディングコンテキストに追加されません。

拡張機能に関連付けられているsettingsプロパティ、形式、拡張機能によって提供されるライブデータの使用方法については、拡張機能のドキュメントを参照してください。

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

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

拡張機能は、settingsプロパティも提供して、利用可能なライブデータオブジェクトをデータバインディングで使用するための名前をドキュメントで定義できるようにする必要があります。以下は、そのデータオブジェクトを拡張機能がドキュメント化した場合の例を示しています。

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

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

{
  "type": "APL",
  "version": "2024.3",
  "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拡張機能がない場合のフォールバック",
        "type": "Text",
        "text": "FishFeederがありません"
      }
    ]
  }
}

上の例では、「aplext:fishfeeder:10」拡張機能によって公開されるライブデータオブジェクトに対して、「fishType」というデータバインディング名が定義されています。拡張機能は、ライブデータオブジェクトfishTypeを「fishType」としてグローバルデータバインディングコンテキストに追加します。

拡張機能の画像フィルター

APL拡張機能は、画像を変更するカスタムの画像フィルターを定義できます。拡張機能の画像フィルターは、通常のフィルターと同じように、Imageコンポーネントのfiltersプロパティにフィルターを含めることで呼び出します。フィルターのtypeは「EXTENSION_NAME:FILTER_NAME」に設定します。拡張機能をリクエストしたときに定義したnameプロパティが、その拡張機能によって提供されるフィルターを呼び出すときのnamespaceとして使用されます。

たとえば、「Canny」フィルターを提供する拡張機能があるとします。このフィルターは、画像に対してCanny法によるエッジ検出アルゴリズムを実行します。このアルゴリズムは、下限しきい値と上限しきい値の2つの入力を受け取ります。どちらも0.0～1.0の正規化された値です。次の表は、このフィルターによって使用されるプロパティです。

プロパティ	型	デフォルト	説明
`type`	Canny	必須	フィルターのタイプを定義します。
`lower`	数値	0.1	エッジ検出の下限を指定します。
`upper`	数値	0.9	エッジ検出の上限を指定します。
`source`	整数	-1	ソース画像のインデックスです。

次の例は、APLドキュメントでこのフィルターを使用して、エッジに黄色い色を付ける方法を示しています。

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "name": "Edges",
      "uri": "aplext:edgedetectorfilters:11"
    }
  ],
  "mainTemplate": {
    "items": {
      "type": "Image",
      "width": "100%",
      "height": "100%",
      "scale": "best-fit",
      "source": "https://example.com/images/imageToProcess.png",
      "filters": [
        {
          "type": "Color",
          "color": "yellow"
        },
        {
          "type": "Edges:Canny",
          "lower": 0.2,
          "upper": 0.7,
          "source": -2
        },
        {
          "type": "Blend",
          "mode": "multiply"
        }
      ]
    }
  }
}

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

フィードバックを送信

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