Alexa.Presentation.APLインターフェースのリファレンス

Alexa.Presentation.APLインターフェースは、Echo Showなどの画面付きデバイスでコンテンツを表示するディレクティブとリクエストを提供します。

supportedInterfacesのAlexa.Presentation.APL

ユーザーのデバイスにAPL対応の画面がある場合は、context.System.device.supportedInterfacesオブジェクトに[Alexa.Presentation.APL]が含まれています。

APL対応のデバイスのLaunchRequest

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {
      "device": {
        "deviceId": "amzn1.ask.device.1",
        "supportedInterfaces": {
          "AudioPlayer": {},
          "Alexa.Presentation.APL": {
            "runtime": {
              "maxVersion": "1.9"
            }
          }
        }
      },
      "apiEndpoint": "https://api-amazonalexa.amazon.com",
      "apiAccessToken": ""
    },
    "Viewport": {
      "experiences": [
        {
          "canRotate": true,
          "canResize": true
        },
        {
          "canRotate": false,
          "canResize": false
        }
      ],
      "shape": "RECTANGLE",
      "pixelWidth": 1024,
      "pixelHeight": 600,
      "dpi": 160,
      "currentPixelWidth": 640,
      "currentPixelHeight": 500,
      "touch": [
        "SINGLE"
      ],
      "keyboard": [
        "DIRECTION"
      ],
      "video": {
        "codecs": [
          "H_264_42",
          "H_264_41"
        ]
      }
    }
  },
  "request": {
    "type": "LaunchRequest",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2019-06-27T15:52:19Z",
    "locale": "ja-JP",
    "shouldLinkResultBeReturned": false
  }
}

Alexa.Presentation.APLディレクティブを返す前に、必ずsupportedInterfacesを確認してください。ASK SDKでこの確認を行う例は、ASK SDK v2でのAlexa Presentation Languageの使用で、ユーザーのデバイスがAPLに対応していることを確認するを参照してください。

利用可能なextensions

Extensionsは、追加のAPL機能を提供するオプションの拡張機能です。一部のextensionsは、スキルマニフェストでextensionを宣言する必要があります。ユーザーのデバイスがこれらのextensionをサポートしている場合、contextオブジェクトにはExtensions.availableプロパティが含まれます。このプロパティには、使用可能なextensionのURIが各項目のキーに指定されたマップが含まれます。

次の例は、Smart MotionとEntity Sensingをサポートするデバイスからのリクエストを示しています。

{
  "version": "1.0",
  "session": {},
  "context": {
    "AudioPlayer": {
      "playerActivity": "IDLE"
    },
    "Viewports": [
      {
        "type": "APL",
        "id": "<string>"
      }
    ],
    "Extensions": {
      "available": {
        "alexaext:smartmotion:10": {},
        "alexaext:entitysensing:10": {}
      }
    }
  }
}

context.Extensionsプロパティには、次の条件の両方を満たすエクステンションが含まれます。

• スキルマニフェストのrequestedExtensionsプロパティでリクエストされていること。

  マニフェストでextensionをリクエストする方法の詳細については、スキルマニフェストでextensionをリクエストするを参照してください。

• extensionがこのデバイスでサポートされていること。

マニフェストに含めることができるのは一部のextensionです。要件を確認するには使用する各extensionのトピックを参照してください。

ディレクティブ

RenderDocumentディレクティブ

指定されたdocumentに含まれているAPLコンテンツを表示するようデバイスに命令します。オプションで、1つまたは複数のdatasourcesを指定してコンテンツをドキュメントにバインドすることもできます。

次のRenderDocumentの例では、2つのTextコンポーネントとhelloworldDataというデータソースを含むドキュメントを送信します。

{
  "type": "Alexa.Presentation.APL.RenderDocument",
  "token": "helloworldToken",
  "document": {
    "type": "APL",
    "version": "1.9",
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": [
        {
          "type": "Container",
          "height": "100%",
          "width": "100%",
          "items": [
            {
              "type": "Text",
              "id": "helloTextComponent",
              "text": "${payload.helloworldData.properties.helloText}",
              "textAlign": "center",
              "textAlignVertical": "center",
              "maxLines": 3,
              "grow": 1
            },
            {
              "type": "Text",
              "id": "newHelloTextComponent",
              "text": "${payload.helloworldData.properties.newHelloText}",
              "textAlign": "center",
              "textAlignVertical": "bottom",
              "maxLines": 3,
              "opacity": 0
            }
          ]
        }
      ]
    }
  },
  "datasources": {
    "helloworldData": {
      "type": "object",
      "objectId": "helloworld",
      "properties": {
        "helloText": "ハローワールド。 このAPLドキュメントは、helloworldDataというデータソースのテキストを表示します。",
        "newHelloText": "元のハローテキストを非表示にして、これを表示しました。"
      }
    }
  }
}

オーサリングツールでスキルとともにドキュメントを保存し、RenderDocumentディレクティブにリンクすることもできます。次の例では、"hello world"ドキュメントが"helloworld-by-link"という名前で保存されていることを前提としています。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.RenderDocument",
      "token": "helloworldToken",
      "document": {
        "src": "doc://alexa/apl/documents/helloworld-by-link",
        "type": "Link"
      },
      "datasources": {
        "helloworldData": {
          "type": "object",
          "objectId": "helloworld",
          "properties": {
            "helloText": "ハローワールド。 このAPLドキュメントは、helloworldDataというデータソースのテキストを表示します。",
            "newHelloText": "元のハローテキストを非表示にして、これを表示しました。"
          }
        }
      }
    }
  ]
}

RenderDocumentのプロパティ

documentプロパティには、ドキュメントのURLが設定されたsrcプロパティか、ドキュメント全体のJSONが常に含まれている必要があります。

ASK SDK v2でRenderDocumentを送信する方法の例は、ASK SDK v2でのAlexa Presentation Languageの使用ページのリクエストハンドラーの応答でRenderDocumentを返すを参照してください。

オーサリングツールに保存されたAPLドキュメントへのリンク

オーサリングツールでAPLドキュメントを保存すると、RenderDocumentディレクティブでそのドキュメントをリンクすることができます。つまり、APLドキュメントのJSONをエクスポートしてコードにコピーする必要はありません。

オーサリングツールのドキュメントへリンクするには、次の構文を記述します。

doc://alexa/apl/documents/<document-name>

<document-name>は、オーサリングツールでドキュメントを保存するときに使用した名前です。

オーサリングツールでのドキュメントのビルドと保存の詳細については、オーサリングツールを使用したAPLドキュメントの作成を参照してください。

RenderDocumentとその他のスキルディレクティブ

• 応答では、RenderDocumentと、Dialog.Delegateを除く任意のDialogディレクティブを組み合わせることができます。たとえば、Dialog.ElicitSlotを使用して、ユーザーにスロット値の入力を求め、同時にRenderDocumentでそのスロットに関連する情報を画面に表示できます。
• 応答では、RenderDocumentと次のインターフェースのディレクティブを組み合わせることはできません。
  • AudioPlayer
  • Display
  • VideoApp

ExecuteCommandsディレクティブ

tokenによって識別され、現在レンダリングされているドキュメントに対して、指定したcommandsを実行するようにデバイスに指示します。

次の例では、helloworldTokenトークンで識別されたドキュメントに対して動作するExecuteCommandsディレクティブを送信します。このディレクティブには、次の2つのコマンドがあります。

• 1番目のAnimateItemコマンドは、helloTextComponentコンポーネントの不透明度を3秒間で0に変更して、ビューからフェードアウトさせます。
• 2番目のAnimateItemコマンドは、newHelloTextComponentコンポーネントの不透明度を3秒間で0から1に変更して、ビューにフェードインさせます。

{
  "type": "Alexa.Presentation.APL.ExecuteCommands",
  "token": "helloworldToken",
  "commands": [
    {
      "type": "AnimateItem",
      "componentId": "helloTextComponent",
      "duration": "3000",
      "easing": "linear",
      "value": [
        {
          "property": "opacity",
          "to": "0.0"
        }
      ]
    },
    {
      "type": "AnimateItem",
      "componentId": "newHelloTextComponent",
      "duration": "3000",
      "easing": "linear",
      "value": [
        {
          "property": "opacity",
          "to": "1.0"
        }
      ]
    }
  ]
}

ExecuteCommandsプロパティ

ExecuteCommandsディレクティブは、tokenで識別された特定のドキュメントに対して、コマンドを実行します。ExecuteCommandsディレクティブで指定するtokenは、対象となるドキュメントを送信したRenderDocumentディレクティブで指定したtokenと一致する必要があります。

RenderDocumentディレクティブとExecuteCommandsディレクティブは、同じスキルの応答で送信することも、別の応答で送信することもできます。

• 1つの応答に両方のディレクティブが含まれている場合、両方のディレクティブでtokenが一致すれば、デバイスは指定されたドキュメントを表示した後に、コマンドを実行します。

• ExecuteCommandsを別の応答で返すと、デバイスは現在viewportに表示されているドキュメントに対して、コマンドを実行します。tokenは、これより前にRenderDocumentディレクティブで使用したtokenと一致する必要があります。

  このシナリオでExecuteCommandsを送信する前に、リクエストの視覚的なコンテキストを確認して、ドキュメントが現在表示されていることを確認します。リクエストのcontext.["Alexa.Presentation.APL"].tokenプロパティから、現在表示されているドキュメントのtokenを取得できます。

いずれの場合も、tokenの値がディレクティブ間で一致しなければ、コマンドは実行されません。

以下のリクエストの例では、viewportがhelloworldWithButtonTokenトークンを持つドキュメントを表示していることを示しています（説明を簡潔にするために、このリクエストの一部は省略されています）。

{
  "version": "1.0",
  "session": {},
  "context": {
    "Alexa.Presentation.APL": {
      "token": "helloworldWithButtonToken",
      "version": "APL_WEB_RENDERER_GANDALF",
      "componentsVisibleOnScreen": [
        {
          "uid": ":1000",
          "position": "1024x600+0+0:0",
          "type": "text",
          "tags": {
            "viewport": {}
          },
          "children": [
            {
              "id": "fadeHelloTextButton",
              "uid": ":1002",
              "position": "270x70+377+450:0",
              "type": "text",
              "tags": {
                "focused": false,
                "clickable": true
              },
              "entities": []
            }
          ],
          "entities": []
        }
      ]
    },
    "System": {},
    "Viewport": {},
    "Viewports": []
  },
  "request": {}
}

このプロパティを確認して、ASK SDKでExecuteCommandsを返す方法の例は、ASK SDK v2でのAlexa Presentation Languageの使用ページのリクエストハンドラーの応答でExecuteCommandsを返すを参照してください。

ExecuteCommandsとその他のスキルディレクティブ

応答では、ExecuteCommandsと次のインターフェースのディレクティブを組み合わせることはできません。

• AudioPlayer
• Dialog
• Display
• VideoApp

SendIndexListDataディレクティブ

LoadIndexListDataリクエストに応答して、表示する一連の新しいリスト項目を送信します。dynamicIndexListデータソースを次に表示する項目に含めます。応答にoutputSpeechまたはshouldEndSessionを含めないでください。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.SendIndexListData",
      "correlationToken": "alexa-provided-correlation-token",
      "listId": "my-list-id",
      "listVersion": 3,
      "startIndex": 11,
      "minimumInclusiveIndex": 11,
      "maximumExclusiveIndex": 21,
      "items": [
        {"primaryText":"item 11"},
        {"primaryText":"item 12"},
        {"primaryText":"item 13"},
        {"primaryText":"item 14"},
        {"primaryText":"item 15"},
        {"primaryText":"item 16"},
        {"primaryText":"item 17"},
        {"primaryText":"item 18"},
        {"primaryText":"item 19"},
        {"primaryText":"item 20"}
      ]
    }
  ]
}

プロアクティブな読み込み

スキルがLoadIndexListDataリクエストに応答する場合は、 correlationTokenを指定する必要があります。想定されるcorrelationTokenがSendIndexListDataディレクティブで指定されていない場合、Alexaはスキルの応答を拒否します。

LoadIndexListDataリクエストへの応答以外で、一連のリスト項目を送信する場合は、correlationTokenを省略します。

SendTokenListDataディレクティブ

LoadTokenListDataリクエストに応答して、表示するリスト項目の新しいページを送信します。dynamicTokenListデータソースを次に表示する項目ページに含めます。応答にoutputSpeechまたはshouldEndSessionを含めないでください。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.SendTokenListData",
      "token": "developer-provided-token",
      "correlationToken": "alexa-provided-correlation-token",
      "listId": "my-list-id",
      "pageToken": "myListPage2",
      "nextPageToken" "myListPage3"
      "items": [
        {"primaryText":"item 11"},
        {"primaryText":"item 12"},
        {"primaryText":"item 13"},
        {"primaryText":"item 14"},
        {"primaryText":"item 15"},
        {"primaryText":"item 16"},
        {"primaryText":"item 17"},
        {"primaryText":"item 18"},
        {"primaryText":"item 19"},
        {"primaryText":"item 20"}
      ]
    }
  ]
}

プロアクティブな読み込み

スキルがLoadTokenListDataリクエストに応答する場合は、correlationTokenを指定する必要があります。想定されるcorrelationTokenがSendTokenListDataディレクティブで指定されていない場合、Alexaはスキルの応答を拒否します。

LoadTokenListDataリクエストへの応答以外で、一連のリスト項目を送信する場合は、correlationTokenを省略します。

UpdateIndexListDataディレクティブ

RenderDocumentディレクティブで、デバイスに既に送信されたデータソースにリスト項目を挿入、設定、削除するには、一連のデータの操作をAlexaに送信します。1つのディレクティブに複数の変更を含めることができます。

{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.UpdateIndexListData",
      "token": "developer-provided-token",
      "listId": "my-list-id",
      "listVersion": 3,
      "operations": [
        {
          "type": "InsertItem",
          "index": 10,
          "item": {
            "primaryText": "項目10の前に挿入された、新しい項目9.5"
          }
        },
        {
          "type": "InsertMultipleItems",
          "index": 12,
          "items": [
            {"primaryText":"項目12の前に挿入された、3つの新しい項目の1番目"},
            {"primaryText":"3つの項目の2番目"},
            {"primaryText":"3つの項目の3番目"}
          ]
        },
        {
          "type": "SetItem",
          "index": 14,
          "item": {"primaryText":"項目14の置換テキスト"}
        },
        {
          "type": "DeleteItem",
          "index": 16
        },
        {
          "type": "DeleteMultipleItems",
          "index": 17,
          "count": 2
        }
      ]
    }
  ]
}

listVersion

更新後のリストの新しいバージョンです。スキルとAlexaの間でリストの一貫性を維持するために使用されます。Alexaは、すべてのリストがバージョン0から始まると仮定しているため、特定のリストに対して発行された最初のUpdateIndexListDataディレクティブはlistIndexを1に設定します。Alexaは、指定されていないディレクティブまたは中間ディレクティブが受信されて処理されるまで、順不同のlistVersionを指定するUpdateIndexListDataディレクティブをすべてバッファーします。

このフィールドはUpdateIndexListDataでは必須ですが、SendIndexListDataでは任意となる場合があります。

• リストの更新情報を挿入、設定、削除しない場合、この値を入力する必要はありません。
• リストに対して挿入、設定、削除操作を実行するときは、すべてのSendIndexListDataディレクティブに対してこの値を入力する必要があります。

したがって、特定のリストについては、Alexaは以下を破棄します。

• listVersionを指定していないSendIndexListDataディレクティブの後に受信された、すべてのUpdateIndexListDataディレクティブ
• UpdateIndexListDataディレクティブの受信後にlistVersionを指定しない、すべてのSendIndexListDataディレクティブ

operations

考えられる更新操作の列挙値です。

InsertItem

指定されたindexのデータソースに1つのitemを挿入します。

リストの範囲内に項目を挿入したり、リストの末尾に項目を追加したりできます。隣接していないインデックスに項目を挿入しようとすると、エラーが発生します。たとえば、現在のインデックスの範囲がM～Nの場合、M～N+1の範囲に項目を挿入できます。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定されたInsertItem操作では、次の処理が実行されます。

• 位置5に新しいitemを挿入します。
• 既存の項目5～9のindexを6～10に更新します。元の項目5は6になり、元の項目6は7になり、以下同様です。
• データソースのmaximumExclusiveIndexプロパティを10から11に更新します。

InsertMultipleItems

指定されたindexにitemsの配列を挿入します。

リストの範囲内に項目を挿入したり、リストの末尾に項目を追加したりできます。隣接していないインデックスに項目を挿入しようとすると、エラーが発生します。たとえば、現在のインデックスの範囲がM～Nの場合、M～N+1の範囲に項目を挿入できます。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定され、itemsで2つの新しい項目が指定されているInsertMultipleItem操作では、次の処理が実行されます。

• 位置5と6に2つの新しい項目を挿入します。
• 元の項目5～9のindexに2を加算します。元の項目5は7になり、元の項目6は8になり、以下同様です。
• データソースのmaximumExclusiveIndexプロパティを10から12に更新します。

SetItem

指定されたindexの項目を指定されたitemに置き換えます。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定されたSetItem操作では、次の処理が実行されます。

• 位置5の既存の項目を新しいitemに置き換えます。

DeleteItem

指定されたindexの項目を削除します。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定されたDeleteItem操作では、次の処理が実行されます。

• 位置5の既存の項目を削除します。
• 既存の項目6～9のindexを5～8に更新します。元の項目6は5になり、元の項目7は6になり、以下同様です。
• データソースのmaximumExclusiveIndexプロパティを10から9に更新します。

DeleteMultipleItems

指定されたindexを開始点として、データソースから指定されたcountの項目を削除します。

たとえば、元のデータソースには項目が10個あり、そのインデックスが0～9だったとします。indexが5に設定され、countが2に設定されたDeleteMultipleItems操作では、次の処理が実行されます。

• 位置5と6の元の項目を削除します。
• 元の項目7～9のindexから2を引きます。元の項目7の新しいインデックスは5になり、元の項目8は項目6になり、元の項目9は7になります。
• データソースのmaximumExclusiveIndexプロパティを10から8に更新します。

リクエスト

LoadIndexListDataリクエスト

AlexaはスキルにLoadIndexListDataリクエストを送信して、dynamicIndexListデータソースについて、より多くのリスト項目をリクエストします。たとえば、以前に読み込まれた項目の最後のほうまでユーザーがスクロールすると、スキルがこのリクエストを受け取ります。

{
  "request": {
    "type": "Alexa.Presentation.APL.LoadIndexListData",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2020-03-12T19:47:02Z",
    "locale": "ja-JP",
    "token": "developer-provided-token",
    "correlationToken": "101",
    "listId": "my-list-id",
    "startIndex": 20,
    "count": 10
  }
}

有効な応答

LoadIndexListDataリクエストには、SendIndexListDataディレクティブを使用して応答できます。

LoadTokenListDataリクエスト

AlexaはスキルにLoadTokenListDataリクエストを送信して、dynamicTokenListデータソースについて、項目の次のページをリクエストします。たとえば、以前に読み込まれた項目の最後近くまでユーザーがスクロールすると、スキルがこのリクエストを受け取ります。

{
  "request": {
    "type": "Alexa.Presentation.APL.LoadTokenListData",
    "requestId": "amzn1.echo-api.request.1",
    "timestamp": "2021-03-12T19:47:02Z",
    "locale": "ja-JP",
    "token": "developer-provided-token",
    "correlationToken": "101",
    "listId": "my-list-id",
    "pageToken": "myListPage2"
  }
}

有効な応答

LoadTokenListDataリクエストには、SendTokenListDataディレクティブを使用して応答できます。

RuntimeErrorリクエスト

APL処理中に発生したエラーをスキルに通知するために送信されます。このリクエストは通知専用です。スキルはRuntimeErrorリクエストに応答を返すことができません。

{
  "type": "Alexa.Presentation.APL.RuntimeError",
  "token": "developer-provided-token",
  "errors": [
    {
      "type": "LIST_ERROR",
      "reason": "LIST_INDEX_OUT_OF_RANGE",
      "listId": "my-list-id",
      "listVersion": 3,
      "operationIndex": 3,
      "message": ""
    }
  ]
}

errors

type

ポリモーフィズムなエラータイプのインジケータ―です。各エラータイプにはタイプ固有のパラメーターを指定できます。

reason

エラータイプ別の失敗の理由です。任意のタイプで使用できる一般的な値は次のとおりです。

• INTERNAL_ERROR – Alexaサービスの予期しない問題です。

LIST_ERROR

考えられる理由については、 エラーの例を参照してください。

UserEventリクエスト

デバイス上のイベントがSendEventコマンドをトリガーすると、AlexaはスキルにAlexa.Presentation.APL.UserEventリクエストを送信します。これにより、デバイスでのユーザーの操作への応答として、スキルサービスがメッセージを受信します。ドキュメント内のコンポーネントでイベントハンドラーを使用すると、SendEventをトリガーできます。たとえば、TouchWrapperコンポーネントには、onPressイベントハンドラーが含まれているとします。このハンドラーをSendEventコマンドに設定すると、ユーザーがviewport上のコンポーネントをタッチしたときにUserEventリクエストを取得できます。

UserEventリクエストには、SendEventコマンドをトリガーしたコンポーネントとイベントに関する情報が含まれています。コンポーネントのイベントハンドラーでSendEventを定義する場合、対応するUserEventリクエストで取得する情報を指定できます。コード内のイベントハンドラーで、これを使用します。

UserEventプロパティ

次の例は、ユーザーがSequenceコンポーネントによってレンダリングされたTouchWrapperコンポーネントのいずれかをタッチするか、リモコンのdパッドで押したときに、スキルにイベントを送信するAPLドキュメントの一部を示しています。

{
  "type": "Sequence",
  "id": "myCustomSequence",
  "height": "100vh",
  "data": "${payload.templateData.properties.animalList}",
  "numbered": true,
  "item": {
    "type": "TouchWrapper",
    "id": "animalListTouchWrapper",
    "item": {
      "type": "Text",
      "text": "${data.textToShow}"
    },
    "onPress": [
      {
        "type": "SendEvent",
        "arguments": [
          "listItemPressed",
          "${ordinal}",
          "${data.dataToSend}"
        ]
      }
    ]
  }
}

Sequenceは、templateDataというデータソースを使用して、Sequence内の一連の項目を表示し、UserEventに含めるデータを定義します。次の例は、このデータソースの説明を示しています。

{
  "templateData": {
    "properties": {
      "animalList": [
        {
          "textToShow": "ツチブタ",
          "dataToSend": "animalKey123"
        },
        {
          "textToShow": "アードウルフ",
          "dataToSend": "animalKey124"
        },
        {
          "textToShow": "ヒヒ",
          "dataToSend": "animalKey202"
        }
      ]
    }
  }
}

上記の例では、SendEventコマンドのarguments配列が3つの項目を指定しています。

• 静的テキストは「listItemPressed」です。
• データバインディングコンテキストのordinalプロパティです。TouchWrapperがSequenceの子コンポーネントであるため、このプロパティを使用できます。
• データソースの項目のdataToSendプロパティの値です。

したがって、ユーザーが2番目の項目（「アードウルフ」）を選択すると、スキルは次のようなUserEventリクエストを受け取ります。

{
  "version": "1.0",
  "session": {},
  "context": {},
  "request": {
    "type": "Alexa.Presentation.APL.UserEvent",
    "requestId": "amzn1.echo-api.request.1",
    "token": "token-provided-with-RenderDocument",
    "timestamp": "2020-01-17T16:48:11Z",
    "locale": "ja-JP",
    "arguments": [
      "listItemPressed",
      2,
      "animalKey124"
    ],
    "components": {},
    "source": {
      "type": "TouchWrapper",
      "handler": "Press",
      "id": "animalListTouchWrapper"
    },
  }
}

UserEventのコンポーネントデータを取得する

sourceプロパティとargumentsプロパティで指定されたデータに加えて、viewportに表示される他のコンポーネントに関する情報を取得することもできます。情報を取得するには、各コンポーネントにidプロパティを持つ識別子を割り当てます。次に、SendEventコマンドでcomponents配列に含める各コンポーネントのidを指定します。

たとえば、各コンポーネントには、trueまたはfalseのchecked状態が含まれるとします。SetValueコマンドを使用すると、ユーザーの対話への応答としてchecked状態を変更できます。次のAlexaButtonの例では、ユーザーがボタンを選択したときにchecked状態を切り替え、ボタンのテキストを変更します。

{
  "type": "AlexaButton",
  "id": "idForTheToggleButton",
  "buttonText": "Toggle button: false",
  "primaryAction": [
    {
      "type": "SetValue",
      "componentId": "idForTheToggleButton",
      "property": "checked",
      "value": "${!event.source.value}"
    },
    {
      "type": "SetValue",
      "componentId": "idForTheToggleButton",
      "property": "buttonText",
      "value": "Toggle button: ${!event.source.value}"
    }
  ],
  "spacing": "@spacingSmall",
  "alignSelf": "center"
}

次に、ドキュメント内の別のTouchWrapperがSendEventをトリガーして、次の例に示すように、ボタンIDidForTheToggleButtonをcomponents配列に含めます。

{
  "type": "TouchWrapper",
  "id": "idForTheTouchWrapper",
  "spacing": "@spacingSmall",
  "alignSelf": "center",
  "onPress": [
    {
      "type": "SendEvent",
      "arguments": [
        "textWasPressed",
        "このデータをスキルに送信する"
      ],
      "components": [
        "idForTheToggleButton",
        "idForTheTextComponent"
      ]
    }
  ],
  "item": {
    "type": "Text",
    "id": "idForTheTextComponent",
    "color": "@colorAccent",
    "text": "クリックすると、スキルにUserEventが送信されます。"
  }
}

ユーザーはトグルボタンを繰り返し選択して、その状態をtrueとfalseのいずれかに切り替えられます。ユーザーが「クリックすると...」テキストを選択すると、スキルは次のUserEventを受信します。componentsには、現在のchecked状態を持つidForTheToggleButtonが含まれています。

{
  "type": "Alexa.Presentation.APL.UserEvent",
  "requestId": "amzn1.echo-api.request.1",
  "timestamp": "2020-01-20T22:46:04Z",
  "locale": "ja-JP",
  "arguments": [
    "textWasPressed",
    "このデータをスキルに送信する"
  ],
  "components": {
    "idForTheTextComponent": "クリックすると、スキルにUserEventが送信されます。",
    "idForTheToggleButton": true
  },
  "source": {
    "type": "TouchWrapper",
    "handler": "Press",
    "id": "idForTheTouchWrapper"
  },
  "token": "token-provided-with-RenderDocument"
}

サンプルドキュメント： UserEventのコンポーネントを取得する

{
    "type": "APL",
    "version": "1.9",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.9"
        }
    ],
    "mainTemplate": {
        "parameters": [
            "payload"
        ],
        "items": [
            {
                "type": "Container",
                "paddingTop": "@spacing2XLarge",
                "paddingLeft": "@marginHorizontal",
                "paddingRight": "@marginHorizontal",
                "width": "100vw",
                "height": "100vh",
                "items": [
                    {
                        "type": "AlexaButton",
                        "id": "idForTheToggleButton",
                        "buttonText": "Toggle button: false",
                        "primaryAction": [
                            {
                                "type": "SetValue",
                                "componentId": "idForTheToggleButton",
                                "property": "checked",
                                "value": "${!event.source.value}"
                            },
                            {
                                "type": "SetValue",
                                "componentId": "idForTheToggleButton",
                                "property": "buttonText",
                                "value": "Toggle button: ${!event.source.value}"
                            }
                        ],
                        "spacing": "@spacingSmall",
                        "alignSelf": "center"
                    },
                    {
                        "type": "TouchWrapper",
                        "id": "idForTheTouchWrapper",
                        "spacing": "@spacingSmall",
                        "alignSelf": "center",
                        "onPress": [
                            {
                                "type": "SendEvent",
                                "arguments": [
                                    "textWasPressed",
                                    "このデータをスキルに送信する"
                                ],
                                "components": [
                                    "idForTheToggleButton",
                                    "idForTheTextComponent"
                                ]
                            }
                        ],
                        "item": {
                            "type": "Text",
                            "id": "idForTheTextComponent",
                            "color": "@colorAccent",
                            "text": "クリックすると、スキルにUserEventが送信されます。"
                        }
                    }
                ]
            }
        ]
    }
}

ASK SDKでUserEventのハンドラーを作成する方法の例は、ASK SDK v2でのAlexa Presentation Languageの使用で、UserEventリクエストを処理するを参照してください。

有効な応答タイプ

UserEventリクエストに対して、スキルは標準的な応答で応答できます。Dialog.Delegateを除き、すべてのカスタムスキルディレクティブを含めることができます。

エラーの例

エラーが発生すると、スキルはRuntimeErrorリクエストを受信します。

以下の表に、起こりうるエラーの例をまとめます。

スキルリクエストのViewportオブジェクト

スキルに送信されるリクエストには必ず、ユーザーのデバイスでサポートされているviewportに関する情報が含まれています。この情報をコードで使用して、適切な応答を作成できます。

画面付きデバイスの場合、viewport情報はcontext.Viewportオブジェクトに格納されています。

また、viewport情報は、viewportプロパティのデータバインディングコンテキストでも使用できます。データバインディングコンテキストで使用可能な具体的な情報は、スキルリクエストで使用可能な情報とは異なります。詳細については、データバインディングコンテキストのViewportオブジェクトを参照してください。

• スキルコードにviewport情報が必要な場合は、スキルリクエストでcontext.Viewportオブジェクトを使用します。
• APLドキュメントでviewport情報が必要な場合は、データバインディングコンテキストでviewportプロパティを使用します。たとえば、特定のviewportでのみ特定のコンポーネントを表示するためのwhen条件を作成します。データバインディングコンテキストのViewportオブジェクトを参照してください。

次の例では、context.Viewportオブジェクトを使用したスキルリクエストを示しています。説明を簡潔にするために、一部の詳細を省略しています。

{
  "version": "1.0",
  "session": {},
  "context": {
    "Viewports": [
      {
        "type": "APL",
        "id": "main",
        "shape": "RECTANGLE",
        "dpi": 213,
        "presentationType": "STANDARD",
        "canRotate": false,
        "configuration": {
          "current": {
            "mode": "HUB",
            "video": {
              "codecs": [
                "H_264_42",
                "H_264_41"
              ]
            },
            "size": {
              "type": "DISCRETE",
              "pixelWidth": 1280,
              "pixelHeight": 800
            }
          }
        }
      }
    ],
    "Viewport": {
      "experiences": [
        {
          "arcMinuteWidth": 346,
          "arcMinuteHeight": 216,
          "canRotate": false,
          "canResize": false
        }
      ],
      "mode": "HUB",
      "shape": "RECTANGLE",
      "pixelWidth": 1280,
      "pixelHeight": 800,
      "dpi": 213,
      "currentPixelWidth": 1280,
      "currentPixelHeight": 800,
      "touch": [
        "SINGLE"
      ],
      "video": {
        "codecs": [
          "H_264_42",
          "H_264_41"
        ]
      }
    },
    "Extensions": {
      "available": {
        "aplext:backstack:10": {}
      }
    },
    "System": {}
  },
  "request": {}
}

viewportプロパティ

viewportオブジェクトでは、次のプロパティが定義されています。

experiences

experiencesプロパティには、デバイスがサポートしているエクスペリエンスのタイプのリストが含まれています。エクスペリエンスのタイプは、viewportがサポートするモードによって異なります。この情報を使用して、特定のエクスペリエンスでのスキルの動作を最適化できます。たとえば、タブレットデバイスには2つの異なるエクスペリエンスがあります。1つは、タブレットがドックに装着されている場合、もう1つはユーザーがタブレットを手に持っている場合です。これらの場合、スキルの表示応答は両方のエクスペリエンスに最適化される必要があります。デバイスの所有者が、自由にエクスペリエンスを切り替えることができるようにするためです。

experienceプロパティ

experiencesプロパティは、廃止されたarcMinuteWidthプロパティとarcMinuteHeightプロパティについても報告します。これらのプロパティは利用可能ですが、廃止されています。代わりに、modeプロパティを使って、デバイスの画面を見る距離と利用可能なモダリティを判断します。

mode

デバイスのタイプを表します。

pixelHeightおよびpixelWidth

pixelHeightおよびpixelWidthプロパティは、高さと幅が上限の場合にviewportで表示されるピクセル数を表します。これらの値は静的なデバイスの向きとみなされ、viewportの領域が現在ほかのアプリケーションで使用されているかいないかに関係なく、viewport全体のサイズを表します。

currentPixelWidthおよびcurrentPixelHeight

currentPixelWidthおよびcurrentPixelHeightプロパティは、Alexaがエクスペリエンスをレンダリングできる縦横のピクセル数を表します。これらの値も静的なデバイスの向きとみなされます。

shape

画面のshapeは、ROUND、RECTANGLEのどちらかに設定されます。

dpi

画面非依存ピクセル（dp）は、携帯電話を見るときの距離で画面を持ち、画面のピクセル密度が1インチ（3cm）あたり約160ピクセルであると仮定した場合の画面のビジュアルサイズを表す測定単位です。物理的な大きさが同じ2つの画面を同じ距離から見た場合、画面の実際のピクセル密度にかかわらず、2つの画面のdpディメンションはほぼ同じになります。

viewportのdpi（インチあたりのドット数）とは、人が見たとおりのポイントまたはピクセルのサイズを表した値であり、画面の実際のインチあたりのピクセル数とは異なります。dpiを求める公式は次のとおりです。

dpi = 160 * （ピクセルサイズ／dpサイズ）

簡略化のため、dpiの値は120、160、240、320などのバケットにまとめられています。

touch

touchプロパティは、デバイスがサポートするタッチ入力の種類を表します。touch配列には、次の値を含めることができます。

• SINGLE - デバイスがシングルタッチ入力をサポートしていることを示します。

keyboard

keyboardプロパティは、viewportとの対話に使用できる物理ボタン入力メカニズムを表します。keyboard配列には、次の値を含めることができます。

• DIRECTION - ボタンと同様に、現在の位置で選択する上下左右方向の入力があります。

video

videoプロパティは、デバイスでのビデオ再生に使用できる技術を詳細に指定します。videoプロパティを使用して、APL応答に送信するビデオリソースの種類を決定します。たとえば、スキルのAPL応答が、デバイスがサポートするビデオコーデックのレベルに応じて、異なるエンコードのビデオリソースを返す場合があります。

画面付きのデバイスでも、ビデオ再生をサポートしていないものもあることに注意してください。この場合、videoプロパティはありません。スキルにビデオが含まれる場合、このプロパティを確認して、ビデオをサポートしていないデバイス向けに適切なエクスペリエンスを提供するようにしてください。ビデオをサポートしていないデバイスにVideoを送信する場合は、そのコンポーネントは画面上に表示されますが、コンテンツは表示されないため、ユーザーには画面に空白の領域が見えることになります。

videoプロパティ

コードのviewport情報にアクセスする

Alexa Skills Kit SDKには、スキルリクエストコンテキストのデータを使用してデバイスのviewportプロファイルを計算する関数が含まれています。これらの関数は廃止になっており、推奨されません。代わりに、Viewportプロファイルパッケージの@viewportProfileリソースを使用して、さまざまなデバイスに対応するAPLドキュメントを作成します。

@viewportProfileリソースおよびレスポンシブ対応ドキュメントの詳細については、以下を参照してください。

• Viewportプロファイル
• レスポンシブ対応のAPLドキュメントを作成する

以下の関数は廃止になっており、推奨されません。

• Node – getViewportProfile
• Python – get_viewport_profile
• Java – ViewportUtils.getViewportProfile

Alexa Skills Kitで廃止になった機能の一覧については、廃止された機能を参照してください。

サービスインターフェースのリファレンス（JSON）

リクエストの形式と標準のリクエストタイプ：

• カスタムスキルのJSONインターフェースのリファレンス
• 標準のリクエストタイプのリファレンス

インターフェース：

• Alexa.Presentation.APLインターフェース（このドキュメント）
• Alexa.Presentation.APLTインターフェース
• Alexa.Presentation.HTMLインターフェースのリファレンス
• AudioPlayerインターフェース
• Connectionsインターフェース
• Dialogインターフェース
• PlaybackControllerインターフェース
• VideoAppインターフェース

関連トピック

• ASK SDK v2でのAlexa Presentation Languageの使用
• APLドキュメント
• SendEventコマンド
• スキルに視覚要素とオーディオを追加する

最終更新日: 2022 年 05 月 25 日