Alexa APLのParametersについて

覚書。

mainTemplateでのParametersの扱い

.mainTemplate.parametersに指定した変数でハンドルできるようになる。

{
    ...略
    "mainTemplate": {
        "parameters": [
            "payload"
        ],
        "items": [
            {
                "type": "Container",
                "items": [
                    {
                        "type": "AlexaHeader",
                        "headerTitle": "${payload.bodyTemplate7Data.title}",

parameterの型について

サンプルではstringの配列ですが、objectでの登録が推奨の様子です。

手間を省くため、パラメーターオブジェクトの代わりに単一のパラメーター名を使用できます（{ "name": "title", ... }の代わりに"title"など）。この形式は非推奨ですが、強制型変換やデフォルト値が不要な場合に用いることで、レイアウトの定義を手短に行うことができます。
https://developer.amazon.com/ja/docs/alexa-presentation-language/apl-layout.html#parameters

なので以下の２つは等価です。

"parameters": ["payload"]

"parameters": [{
  "name": "payload",
  "type": "any"
}]

ASK SDK(Node.js)からデータを受け取る

だいたいこんな感じでAPLのレンダーを指定します。
documentでAPLのJSONを読んで、datasourcesのオブジェクトが.mainTemplate.parametersで指定した値に入ります。

   .addDirective({
        type: 'Alexa.Presentation.APL.RenderDocument',
        token: 'pagerToken',
        version: '1.0',
        document: require('./pager.json'),
        datasources: {
                examplePayload: {
                        title: "hello Alexa"
                }
        }
   })

これを受け取るにはこう書きます。

{
    "type": "APL",
    "version": "1.0",
    "theme": "dark",
    "import": [
        {
            "name": "alexa-layouts",
            "version": "1.0.0"
        }
    ],
    "resources": [],
    "styles": {},
    "layouts": {},
    "mainTemplate": {
        "parameters": [{
          "name": "payload",
          "type": "any"
        }],
        "items": [
            {
                "type": "Container",
                "items": [
                    {
                        "type": "AlexaHeader",
                        "headerTitle": "${payload.examplePayload.title}",
                        "headerAttributionImage": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png"
                    }
                ]
            }
        ]
    }
}

layoutsでのParametersの扱い

layoutsで利用することで、再利用可能なコンポーネントを増やせます。

    "layouts": {
        "myFirstLayout": {
            "parameters": [
                {
                    "name": "title",
                    "description": "Title",
                    "type": "string",
                    "default": "Hello"
                }, "subTitle"
            ],
            "item": [
                {
                    "type": "Text",
                    "text": "<b>${title}:</b>${subTitle}"
                }
            ]
        }
    },

こちらで使う場合はデフォルト値なども指定できるようすです。stringのまま突っ込んでも動きます。
使うときはこんな感じ。

    "mainTemplate": {
        "parameters": [],
        "items": [
            {
                "type": "myFirstLayout",
                "title": "Hola",
                "subTitle": "こんにちは"
            },

このサンプルではあまりありがたみがないですが、ヘッダーフッターなどをちゃんと作り込んでいくなら必須でしょう。