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



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

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

supportedInterfacesのAlexa.Presentation.APL

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

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 MotionEntity 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.8",
    "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のプロパティ

プロパティ 必須 説明

type

文字列

Alexa.Presentation.APL.RenderDocumentに設定します。

token

文字列

ドキュメントを指定する文字列です。ドキュメントを参照する後続のディレクティブを発行するために使用します。たとえば、ExecuteCommandsディレクティブを送信するときにこのトークンが必要となります。

document

オブジェクト

デバイスに送信するAPLドキュメントを表すオブジェクト。

document.typeが"APL"の場合、documentには完全なJSONドキュメントが含まれている必要があります。

document.typeが"Link"の場合、documentにはドキュメントを参照するためのsrcプロパティが含まれている必要があります。

document.type

次のいずれかになります: APLLink

送信するドキュメントの種類を示します。documentに完全なドキュメントオブジェクトが含まれている場合は、"APL"に設定します。document.srcにドキュメントへのリンクが含まれている場合は、"Link"に設定します。

document.src

URL

document.typeLinkの場合

オーサリングツールでドキュメントを識別するURLです。APLの場合、リンクの構文はdoc://alexa/apl/documents/<document-name>です。<document-name>をオーサリングツールでドキュメントを保存するときに使用した名前に置き換えます。document.typeAPLの場合は、このプロパティを含めないでください。

sources

追加ドキュメントのマップ、またはドキュメントへの参照

名前が付けられたAPLAドキュメントまたはリンクを含むオブジェクトです。これらのドキュメントは、aplAudioToSpeechトランスフォーマーのtemplateパラメーターで参照できます。

datasources

データソースオブジェクトのマップ

APLドキュメントにデータをバインドするために、ほかのオブジェクトを含むことができるオブジェクトです。

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

ASK SDK v2RenderDocumentを送信する方法の例は、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プロパティ

プロパティ 必須 説明

type

文字列

Alexa.Presentation.APL.ExecuteCommandsに設定します。

token

文字列

これらのコマンドの対象となるドキュメントを表示するためのRenderDocumentコマンドを識別する文字列です。

commands

コマンド配列

トークンによって識別され、レンダリングされたドキュメントで実行されるコマンドです。このコマンド配列は、暗黙的なSequentialコマンドのように動作します。つまり、コマンドは並列ではなく、順番に実行されます。

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を含めないでください。

プロパティ 必須 説明

type

ディレクティブ

Alexa.Presentation.APL.SendIndexListDataに設定します。

correlationToken

文字列

はい(LoadIndexListDataへの応答として送信された場合)

LoadIndexListDataリクエストに含まれる相関トークンです。LoadIndexListDataへの応答として送信される場合は必須です。それ以外の場合は省略できます。プロアクティブな読み込みを参照してください。

listId

文字列

この応答で更新するリストの識別子です。

listVersion

整数

更新後のリストの新しいバージョン番号で、スキルとデバイス間のリストの一貫性を維持するために使用されます。UpdateIndexListDataを使用して同じリストを更新する場合は必須です。それ以外の場合は必須ではありません。

startIndex

整数

項目の配列の最初の要素のインデックスです。

minimumInclusiveIndex

文字列

配列の最初の項目のインデックスです。値を入力すると、前の操作で指定された値がこの値に置き換えられます。このプロパティを指定しないと、最小インデックスが不明となり、ユーザーが逆方向にスクロールすると、Alexaはより多くの項目をリクエストし続けます(リストは逆方向スクロールリストです)。返された最初の項目のインデックスと等しくなると、それ以上逆方向にスクロールすることはできず、Alexaは項目のリクエストを停止します。

maximumExclusiveIndex

文字列

配列の最後の有効なインデックスに1を加えたものです。値を入力すると、前の操作で指定された値がこの値に置き換えられます。このプロパティを指定しないと、最大インデックスが不明となり、ユーザーが正方向にスクロールすると、Alexaはより多くの項目をリクエストし続けます(リストは正方向スクロールリストです)。このプロパティが、返された最後の項目のインデックスよりも1多くなると、それ以上正方向にスクロールすることはできず、Alexaは項目のリクエストを停止します。

items

配列

リストに追加するオブジェクトの配列です。

{
  "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を指定する必要があります。想定されるcorrelationTokenSendIndexListDataディレクティブで指定されていない場合、Alexaはスキルの応答を拒否します。

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

SendTokenListDataディレクティブ

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

プロパティ 必須 説明

type

ディレクティブ

"Alexa.Presentation.APL.SendTokenListData"に設定します。

correlationToken

文字列

LoadTokenListDataリクエストに含まれる相関トークンです。LoadTokenListDataへの応答として送信される場合は必須です。それ以外の場合は省略できます。プロアクティブな読み込みを参照してください。

listId

文字列

この応答に含まれる項目のリストを識別するIDです。

pageToken

文字列

この応答に含まれる項目の配列のopaqueトークンです。

nextPageToken

文字列

リクエストされたpageTokenで指定されたスクロール方向に応じて、リスト項目データの次ページを取得するopaqueトークンです。このプロパティを指定しない場合は、そのスクロール方向でリストの最後の項目に達していることを示します。つまり、この方向にそれ以上スクロールすることはできません。

items

配列

リストに追加するオブジェクトの配列です。

{
  "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を指定する必要があります。想定されるcorrelationTokenSendTokenListDataディレクティブで指定されていない場合、Alexaはスキルの応答を拒否します。

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

UpdateIndexListDataディレクティブ

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

プロパティ 必須 説明

type

ディレクティブ

Alexa.Presentation.APL.UpdateIndexListDataに設定します。

token

文字列

Alexaに送信されるRenderDocumentディレクティブで指定されたプレゼンテーショントークンです。

listId

文字列

この応答で更新するリストの識別子です。

listVersion

整数

更新後のリストの新しいバージョンです。スキルとAlexaの間でリストの一貫性を維持するために使用されます。

operations

配列

リストに適用する各操作を配列順に並べたものです。Alexaは、配列の次の操作を処理する前に、各項目を完全に適用します。1つの操作を完全に適用すると、変更が行われ、前後の項目のインデックス位置が更新されます。操作の処理中に障害が発生した場合、Alexaは配列内の以降の操作を破棄し、またターゲットデータソースの項目を更新しようとする後続のディレクティブも破棄します。

{
  "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の範囲に項目を挿入できます。

フィールド 必須 説明

index

整数

既存のリストに項目を挿入するインデックスです。挿入するインデックスと同じ、またはそれ以上のインデックスの既存のリスト項目はすべて、インデックスが1つずつ増加します。定義されている場合、データソースのmaximumExclusiveIndexの値も1増加します。

item

オブジェクト

指定されたリストのインデックスに含める項目データです。

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

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

InsertMultipleItems

指定されたindexitemsの配列を挿入します。

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

フィールド 必須 説明

index

整数

既存のリストに、指定された項目の最初の項目を挿入するインデックスです。残りの項目は、順次増加するインデックスで挿入されます。挿入するインデックスと同じ、またはそれ以上のインデックスの既存のリスト項目はすべて、インデックスがitems配列の長さの分だけ増加します。定義されている場合、データソースのmaximumExclusiveIndexの値もitemsの配列の長さの分だけ増加します。

items

配列

指定されたリストのインデックスに含める項目データの配列です。

たとえば、元のデータソースには項目が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に置き換えます。

フィールド 必須 説明

index

整数

既存のリストで置換する項目のインデックスです。リスト内の他のすべての項目の定義とインデックスは変更されません。値が入力されていないインデックスの項目を設定しようとすると、エラーが発生します。

item

オブジェクト

指定されたリストのインデックスの新しい項目データです。

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

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

DeleteItem

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

フィールド 必須 説明

index

整数

既存のリストから削除する項目のインデックスです。削除するindexよりも大きいインデックスの既存のリスト項目はすべて、インデックスが1つずつ減少します。定義されている場合、データソースのmaximumExclusiveIndexの値も1減少します。値が入力されていないインデックスの項目を削除しようとすると、エラーが発生します。

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

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

DeleteMultipleItems

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

フィールド 必須 説明

index

整数

既存のリストで削除する最初の項目のインデックスです。残りの項目は、順次増加するインデックスで削除されます。削除されたインデックスよりも大きいインデックスの既存のリスト項目はすべて、インデックスがcount分減少します。定義されている場合、maximumExclusiveIndexの値もcount分減少します。値が入力されていないインデックスの項目を削除しようとすると、エラーが発生します。

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データソースについて、より多くのリスト項目をリクエストします。たとえば、以前に読み込まれた項目の最後のほうまでユーザーがスクロールすると、スキルがこのリクエストを受け取ります。

プロパティ 必須 説明

type

文字列

Alexa.Presentation.APL.LoadIndexListDataに設定します。

token

文字列

Alexaに送信されるRenderDocumentディレクティブで指定されたプレゼンテーショントークンです。

correlationToken

文字列

リクエストと対応する応答ディレクティブを関連付けるために使用される、Alexaが生成した識別子です。SendIndexListDataディレクティブで応答する場合は、これを含めます。

listId

文字列

項目を取得するリストの識別子です。

startIndex

文字列

取得する項目の最も小さいインデックス(当該値を含む)です。

count

整数

取得する項目の数です。

{
  "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データソースについて、項目の次のページをリクエストします。たとえば、以前に読み込まれた項目の最後近くまでユーザーがスクロールすると、スキルがこのリクエストを受け取ります。

type 文字列 Alexa.Presentation.APL.LoadTokenListDataに設定

token

文字列

Alexaに送信されるRenderDocumentディレクティブで指定されたプレゼンテーショントークンです。

correlationToken

文字列

リクエストと対応する応答ディレクティブを関連付けるために使用される、Alexaが生成した識別子です。SendTokenListDataディレクティブで応答する場合は、これを含めます。

listId

文字列

項目を取得するリストの識別子です。

pageToken

文字列

取得する項目に関連付けられたトークンです。pageTokenに使用する文字列を判断します。スキルはトークンに関連付けられたデータを追跡し、トークンが前、後、いずれのスクロール方向を表しているかを判断できる必要があります。

{
  "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

文字列

Alexaに送信されるRenderDocumentディレクティブで指定されたプレゼンテーショントークンです。

errors

配列

報告されたエラーの配列です。

{
  "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

文字列

発生したエラーの理由を説明します。

message

文字列

人が読める形式でのエラーの説明です。

type

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

プロパティ 説明

LIST_ERROR

dynamicIndexListデータソースの処理に関連するエラーです。

reason

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

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

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

フィールド 必須 説明

listId

文字列

エラーが発生したリストの識別子が含まれます。

listVersion

文字列

エラーが発生した更新によって指定されたlistVersionが含まれます(既知の場合)。

operationIndex

整数

エラーが発生した操作のインデックスが含まれます(既知の場合)。

UserEventリクエスト

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

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

UserEventプロパティ

プロパティ 説明

type

文字列

常にAlexa.Presentation.APL.UserEventに設定します。

token

文字列

このUserEventを送信したRenderDocumentまたはExecuteCommandsディレクティブで指定されたトークンです。

arguments

値の配列

このリクエストをトリガーしたSendEventコマンドのargumentsプロパティで指定された値の配列です。

source

オブジェクト

このイベントの発生元であるAPLコンポーネントとイベントハンドラー(ある場合)の情報です。

components

オブジェクト

このリクエストをトリガーしたSendEventコマンドのcomponentsプロパティで識別される各コンポーネントの値です。

次の例は、ユーザーが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プロパティです。TouchWrapperSequenceの子コンポーネントであるため、このプロパティを使用できます。
  • データソースの項目の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またはfalsechecked状態が含まれるとします。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"
}

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

{
  "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が送信されます。"
  }
}

ユーザーはトグルボタンを繰り返し選択して、その状態をtruefalseのいずれかに切り替えられます。ユーザーが「クリックすると...」テキストを選択すると、スキルは次の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"
}

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

有効な応答タイプ

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

エラーの例

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

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

エラーの説明 例外の理由 システム応答

UpdateIndexListDataに必須フィールドがありません。

なし

Alexaは受信したディレクティブを拒否します。

ディレクティブペイロードまたはリスト項目が長さの上限を超えています。

なし

Alexaは受信したディレクティブを拒否します。

UpdateIndexListDataに認識されないトークンまたはlistIdがあります。

INVALID_PRESENTATION_TOKENまたはINVALID_LIST_ID

Alexaは受信したディレクティブを破棄します。

UpdateIndexListDataまたはSendIndexListDataが指定するlistVersionが、想定よりも大きい値です。

なし

ディレクティブがAlexaに送信され、中間ディレクティブが受信および処理されるまでバッファーされます。

ディレクティブが、指定された期間よりも長くバッファーされています。

MISSING_LIST_VERSION

Alexaはディレクティブを引き続きバッファーします。

Alexaがメモリ不足などの理由で、これ以上順不同のディレクティブをバッファーできないか、バッファーしようとしていません。

MISSING_LIST_VERSION

Alexaは最大のlistVersionを持つ、バッファーされたディレクティブを破棄します。

UpdateIndexListDataまたはSendIndexListDataが指定するlistVersionが、想定よりも低い値です。

DUPLICATE_LIST_VERSION

Alexaは受信したディレクティブを破棄します。

スキルが、認識されない操作タイプを持つUpdateIndexListDataを返しています。

INVALID_OPERATION

Alexaは受信したディレクティブを破棄して、リストを「失敗」状態とし、それ以上の更新を承認しません。

スキルがDynamicTokenListに対してUpdateIndexListDataディレクティブを返しています。

INVALID_DATASOURCE

Alexaは受信したディレクティブを破棄して、リストを「失敗」状態とし、それ以上の更新を承認しません。

スキルが、許可された値の範囲外のインデックスを持つ挿入、設定、削除操作を返しています。

LIST_INDEX_OUT_OF_RANGE

Alexaは受信したディレクティブを破棄して、リストを「失敗」状態とし、それ以上の更新を承認しません。

リストが、listVersionを指定していないSendIndexListDataディレクティブの後に、UpdateIndexListDataディレクティブを受信しています。

MISSING_LIST_VERSION_IN_SEND_DATA

Alexaは受信したディレクティブを破棄して、リストを「失敗」状態とし、それ以上の更新を承認しません。

リストが、UpdateIndexListDataディレクティブの後にlistVersionを指定しないSendIndexListDataディレクティブを受信しています。

MISSING_LIST_VERSION_IN_SEND_DATA

Alexaは受信したディレクティブを破棄して、リストを「失敗」状態とし、それ以上の更新を承認しません。

SendTokenListDataまたはSendIndexListDataが、予期しないcorrelationTokenを指定しています。

なし

デバイスは応答ディレクティブを破棄します。

デバイスが、設定されたタイムアウト内にcorrelationTokenに対するSendTokenListData応答を受信していません。

LOAD_TIMEOUT

何度か再試行しても応答がない場合、デバイスはリストの最後に到達したと見なします。再試行ごとに例外が報告されます。

デバイスが、設定されたタイムアウト内にcorrelationTokenに対するSendIndexListData応答を受信していません。

LOAD_TIMEOUT

何度か再試行しても応答がない場合、デバイスはリスト内でリクエストされた位置を越えてこれ以上のスクロールはできないとみなします(デバイスが既にこの位置を越える項目を読み込んでいる場合は除きます。この場合、デバイスはリクエストされたインデックスで「空白」のリストエントリーを表示します)。

listIdまたはpageTokenの値がcorrelationTokenで想定される値と一致しません。

INCONSISTENT_LIST_IDまたはINCONSISTENT_PAGE_TOKEN

デバイスはlistIdとpageTokenの値を無視し、correlationTokenに想定される値を使用します。

SendTokenListDataディレクティブに項目が含まれず、nextPageTokenが含まれています。

MISSING_LIST_ITEMS

デバイスはnextPageTokenを使ってスクロールします。

SendIndexListDataディレクティブに項目が含まれません。

MISSING_LIST_ITEMS

Alexaは、数回または応答の最小/最大インデックスがリストの最後に達するまで遅延読み込みリクエストを再試行します。

SendTokenListDataディレクティブに項目が含まれず、nextPageTokenが含まれません。

なし

デバイスは(リクエストのスクロール方向で)項目の最後に達したとみなします。

以前にリクエストされたページのディレクティブが、以前の応答とは異なるnextPageTokenを返します。

INCONSISTENT_PAGE_TOKEN

デバイスは新しいnextPageTokenを破棄します。

nextPageTokenが、リストの別の場所で既に使用されているトークンと重複しています。

DUPLICATE_PAGE_TOKEN

デバイスは重複したトークンの値を破棄し、フィールドをnull(リストの最後に達した)とみなします。

以前にリクエストされたページのディレクティブが、以前の応答とは異なる項目数を返します。

INCONSISTENT_PAGE_ITEMS

デバイスは、新しく返された項目数を前の応答で返されたものとしてリストを拡大/縮小します。

任意のフィールドが整数値の範囲を超えています。

なし

Alexaは応答ディレクティブを破棄します。

応答が、デバイスのキャッシュに既に含まれているインデックスの項目を指定しています。

OCCUPIED_LIST_INDEX

デバイスのキャッシュに既に含まれているインデックスの項目データをすべて破棄します。

応答にはリクエストされたものとは異なるstartIndexの項目が含まれています。

なし

報告されたstartIndexの項目を受け入れ(これらの場所には以前に読み込まれた項目がないものとみなして)、受け取ったインデックスから続行します。

maximumExclusiveIndex値が返された項目インデックスを超えています。

LOAD_INDEX_OUT_OF_RANGE

デバイスには、startIndexから(maximumExclusiveIndex - 1)のように、maximumExclusiveIndex範囲に含まれる項目を表示します。

応答に、以前に報告されたnull以外の値とは異なるminimumInclusiveIndexまたはmaximumExclusiveIndexが含まれています。

INCONSISTENT_RANGE

デバイスは以前に読み込まれたリスト項目をすべて破棄し、startIndexから開始し、応答に指定されたminimumInclusiveIndexとmaximumExclusiveIndexのパラメーターや項目の詳細を使用するリストを新たに再入力します。

SendIndexListData応答に、リクエストされた数よりも多くの項目が含まれています。

なし

項目がリクエストされたものとして処理し、既に入力されていたインデックスの項目を破棄します。

SendIndexListData応答に、リクエストされた数よりも少ない項目しか含まれていません。

なし

残りの項目に対してフォローアップリクエストを行います(最小/最大インデックスがリストの最後に到達していないものとみなして)。

スキルリクエストの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

experienceオブジェクトの配列

ユーザーがviewportととの対話で求めている別のモードです。

mode

次のいずれかになります: HUBTVPCMOBILEAUTO

デバイスのモードです。

shape

ROUNDまたはRECTANGLE

viewportの形状です。

pixelHeight

整数

ピクセル単位のviewportの高さです。

pixelWidth

整数

ピクセル単位のviewportの幅です。

currentPixelWidth

整数

現在使用しているピクセル単位のviewportの幅です。

currentPixelHeight

整数

現在使用しているピクセル単位のviewportの高さです。

dpi

整数

viewportのピクセル密度です。

touch

文字列の配列

viewportがサポートするタッチイベントです。

keyboard

文字列の配列

viewportとの対話で使用する入力メカニズムです。

video

オブジェクト

デバイスでのビデオ再生に使用できる技術の仕様です。

experiences

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

experienceプロパティ

プロパティ 型/値 説明

canRotate

ブール値

viewportが90、180、270度回転できるかどうかを示します。

canResize

ブール値

viewportのサイズが変更できるかどうかを示します。

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

mode

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

pixelHeightおよびpixelWidth

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

currentPixelWidthおよびcurrentPixelHeight

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

shape

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

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プロパティ

プロパティ 型/値 説明

codecs

文字列の配列

出力デバイスがサポートするビデオコーデックです。サポートされる値:

  • H_264_41: 最大解像度1080p @ 30fps(コーデックレベル4.1)のH.264、および主機能および高機能プロファイルをサポート(MPおよびHP)
  • H_264_42: 最大解像度1080p @ 60fps(コーデックレベル4.2)のH.264、および主機能および高機能プロファイルをサポート(MPおよびHP)

H_264_41H_264_42のサブセットです。H_264_42を指定するすべてのスキルリクエストは、H_264_41も指定します。すべてのビデオ再生可能なデバイスは、AACおよびMP3オーディオコーデックと共に、MPEG-4 Part-14コンテナ(MP4)もサポートしています。

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

Alexa Skills Kit SDKsには、スキルのリクエストからviewport情報を取得する、ヘルパー関数が含まれます。getViewportProfileメソッドは、context.Viewport内で複数の判断基準を確認して、viewportプロファイルパッケージで使用できるviewportプロファイルに対応する値を返します。

  • HUB-ROUND-SMALL
  • HUB-LANDSCAPE-SMALL
  • HUB-LANDSCAPE-MEDIUM
  • HUB-LANDSCAPE-LARGE
  • TV-LANDSCAPE-XLARGE
  • UNKNOWN-VIEWPORT-PROFILE

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

このサンプルコードは、Alexa Skills Kit SDK for Node.js(v2)を使用しています。 このコードを含む完全な作業用サンプルは、 APL Pager Karaokeサンプルを参照してください。

ハンドラーでは、以下のようにgetViewportProfileにアクセスします。

const Alexa = require('ask-sdk-core');

//...他のコード。

const viewportProfile = Alexa.getViewportProfile(handlerInput.requestEnvelope);

// HUB-LANDSCAPE-MEDIUMなどのViewportProfileを返します。

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

このサンプルコードは、Alexa Skills Kit SDK for Pythonを使用しています。 このコードを含む完全な作業用サンプルは、 APL Pager Karaokeサンプルを参照してください。

ハンドラーでは、以下のようにget_viewport_profileにアクセスします。

from ask_sdk_core.utils import viewport

# 他のコード...

viewport.get_viewport_profile 

# viewport.ViewportProfile.HUB_LANDSCAPE_MEDIUMなどのViewportProfileを返します。

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

このサンプルコードはAlexa Skills Kit SDK for Javaを使用しています。 このコードを含む完全な作業用サンプルは、 APL Pager Karaokeサンプルを参照してください。

ViewportUtils静的クラスを使用して、viewport情報を取得してください。以下のコードは、ViewportProfile列挙値から値を返します。

ViewportProfile viewportProfile = ViewportUtils
    .getViewportProfile(input.getRequestEnvelope());

サービスインターフェースのリファレンス(JSON)

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

インターフェース: