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に対応していることを確認するを参照してください。

RenderDocumentディレクティブ

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

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

{
  "type": "Alexa.Presentation.APL.RenderDocument",
  "token": "helloworldToken",
  "document": {
    "type": "APL",
    "version": "1.3",
    "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のプロパティ

プロパティ 必須 説明
type 文字列 Alexa.Presentation.APL.RenderDocumentに設定します。
token 文字列 ドキュメントを指定する文字列です。ドキュメントを参照する後続のディレクティブを発行するために使用します。たとえば、ExecuteCommandsディレクティブを送信するときにこのトークンが必要となります。
document APLドキュメント Alexaデバイスに送信されるAPLドキュメントを含むオブジェクトです。
datasources データソースオブジェクトのマップ APLドキュメントにデータをバインドするために、ほかのオブジェクトを含むことができるオブジェクトです。

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

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に設定します。
token 文字列 Alexaに送信されるRenderDocumentディレクティブで指定されたプレゼンテーショントークンです。
correlationToken 文字列 はい(LoadIndexListDataへの応答として送信された場合) LoadIndexListDataリクエストに含まれる相関トークンです。LoadIndexListDataへの応答として送信される場合は必須です。それ以外の場合は省略できます。プロアクティブな読み込みを参照してください。
listId 文字列 この応答で更新するリストの識別子です。
listVersion 整数 更新後のリストの新しいバージョン番号で、スキルとデバイス間のリストの一貫性を維持するために使用されます。UpdateIndexListDataを使用して同じリストを更新する場合は必須です。それ以外の場合は必須ではありません。
startIndex 整数 項目の配列の最初の要素のインデックスです。
minimumInclusiveIndex 文字列 配列の最初の項目のインデックスです。値を入力すると、前の操作で指定された値がこの値に置き換えられます。このプロパティを指定しないと、最小インデックスが不明となり、ユーザーが逆方向にスクロールすると、Alexaはより多くの項目をリクエストし続けます(リストは逆方向スクロールリストです)。返された最初の項目のインデックスと等しくなると、それ以上逆方向にスクロールすることはできず、Alexaは項目のリクエストを停止します。
maximumExclusiveIndex 文字列 配列の最後の有効なインデックスに1を加えたものです。値を入力すると、前の操作で指定された値がこの値に置き換えられます。このプロパティを指定しないと、最大インデックスが不明となり、ユーザーが正方向にスクロールすると、Alexaはより多くの項目をリクエストし続けます(リストは正方向スクロールリストです)。このプロパティが、返された最後の項目のインデックスよりも1多くなると、それ以上正方向にスクロールすることはできず、Alexaは項目のリクエストを停止します。
items 配列 リストに追加するオブジェクトの配列です。
{
  "directives": [
    {
      "type": "Alexa.Presentation.APL.SendIndexListData",
      "token": "developer-provided-token",
      "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を省略します。

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":"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に更新します。

エラーの例

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

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

エラーの説明 例外の理由 システム応答
UpdateIndexListDataに必須フィールドがありません。 なし 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は受信したディレクティブを破棄して、リストを「失敗」状態とし、それ以上の更新を承認しません。
スキルが、許可された値の範囲外のインデックスを持つ挿入、設定、削除操作を返しています。 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は受信したディレクティブを破棄して、リストを「失敗」状態とし、それ以上の更新を承認しません。

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ディレクティブを使用して応答できます。

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を除き、すべてのカスタムスキルディレクティブを含めることができます。

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

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

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

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

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

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

{
  "version": "1.0",
  "session": {},
  "context": {
    "System": {},
    "Viewport": {
      "experiences": [
        {
          "arcMinuteWidth": 282,
          "arcMinuteHeight": 141,
          "canRotate": false,
          "canResize": false
        }
      ],
      "shape": "RECTANGLE",
      "pixelWidth": 960,
      "pixelHeight": 480,
      "dpi": 160,
      "currentPixelWidth": 960,
      "currentPixelHeight": 480,
      "touch": [
        "SINGLE"
      ],
      "keyboard": [
        "DIRECTION"
      ],
      "video": {
        "codecs": [
          "H_264_41"
        ]
      }
    },
    "Viewports": [
      {
        "type": "APL",
        "id": "main",
        "shape": "RECTANGLE",
        "dpi": 160,
        "presentationType": "STANDARD",
        "canRotate": false,
        "configuration": {
          "current": {
            "video": {
              "codecs": [
                "H_264_41"
              ]
            },
            "size": {
              "type": "DISCRETE",
              "pixelWidth": 960,
              "pixelHeight": 480
            }
          }
        }
      }
    ]
  },
  "request": {}
}

viewportプロパティ

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

プロパティ 型/値 説明
experiences experienceオブジェクトの配列 ユーザーがviewportととの対話で求めている別のモードです。
shape ROUNDまたはRECTANGLE viewportの形状です。
pixelHeight 整数 ピクセル単位のviewportの高さです。
pixelWidth 整数 ピクセル単位のviewportの幅です。
currentPixelWidth 整数 現在使用しているピクセル単位のviewportの幅です。
currentPixelHeight 整数 現在使用しているピクセル単位のviewportの高さです。
dpi 整数 viewportのピクセル密度です。
touch 文字列の配列 viewportがサポートするタッチイベントです。
keyboard 文字列の配列 viewportとの対話で使用する入力メカニズムです。
video オブジェクト デバイスでのビデオ再生に使用できる技術の仕様です。

エクスペリエンス

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

experienceプロパティ

プロパティ 型/値 説明
canRotate ブール値 viewportが90、180、270度回転できるかどうかを示します。
canResize ブール値 viewportのサイズが変更できるかどうかを示します。

pixel高さおよび幅

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

現在のpixel幅および高さ

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

形状

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

dpi

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

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

dpi = 160 * (ピクセルサイズ/dpサイズ)

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

タッチ

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

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

キーボード

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

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

ビデオ

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)

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

インターフェース: