定型アクションでカスタムタスクが使えるようになった！

2022年3月31日、カスタムタスクが定型アクションから使えるようになったとアナウンスがあった。
Custom Tasks with Alexa Routines offers skill developers a new and effective way to turbocharge skill engagement

定型アクションでカスタムタスクを使うには、カスタムスキルにカスタムタスクを追加してあげる必要がある。カスタムタスクは Alexa Developer Consoleでは作成できないので、ASK CLIを使ってデプロイする必要がある。

以下のロケールで、この機能が使える。（2022年3月31日）
en-AU, en-CA, en-IN, en-GB, en-US, fr-CA, fr-FR, de-DE, hi-IN, it-IT, ja-JP, pt-BR, es-ES, es-MX, and es-US.

定型アクションとは

ざっくり言うと、Alexaができることを自動実行させるもの。実行条件は、キーワードだったり時間だったりと複数の選択肢がある。例えば、朝8:00に音楽をかける。　水の音を検知したら知らせる。　夜23:00に電気を消し、「おやすみ」と言う。　など。

ルーティンに使えるAlexaの "定型アクション" とは？
1つのフレーズ（例：「アレクサ、おやすみ」）や決まった時刻で、音声アシスタントのAlexaが
天気情報や音楽を流すなど複数のことをセットで実行してくれるのが、定型アクションです。
自分のお気に入りの定型アクションを家族や友達にQRコードでシェアできるようになったので、みんなの定型アクションを試して楽しむこともできます。

Alexa定型アクションをセットアップする方法はこちらを参照。

カスタムタスクとは

以下のことをするために必要な情報を定義したものがタスク。
今回は新たにNo.１ができるようになった。これまで定型アクションでは、ただスキルを起動することしかできなかったが、Custom Task with Alexa Routines の登場により、定型アクションに予め値を設定しておくことができるようになった。
例）予め好きな方位を決めておく、予めサイズを指定しておく、など。

No.	できること	概要
1.	Alexa定型アクション	予め指定した値を使ってスキルを起動することができる。
2.	Direct Skill Connections	他のスキルと連携する。
3.	Quick Links for Alexa	スキル起動時に外部から値を渡すことができる。
4.	Timer API（LAUNCH_TASK）	タイマーが鳴った後にスキルを再開する。

Alexa カスタムタスクの実装と動作確認方法は、こちらを参照

定型アクションでカスタムタスクを使用するメリットは？

定型アクションでスキルを選択して起動させることは以前からできていた。では、カスタムタスクを追加すると何が良いのか？それは、スキル起動時のパラメータを予め設定できる点だと思う。

これまでは、スキルを起動させて、スキルとのやり取りの中でスロットとして拾っていた。その値を、事前に設定しておくことができるようになったため、会話のターンの短縮が期待でき、やりたい事に直接アクセスすることが可能となる（スキルの作り方次第ではあるが）。他にもメリットはあると思うけど、これが一番効果が高いと思っている。

定型アクションで使用できるカスタムタスクは３種類

No.	カスタムタスクの種類	概要
1.	パラメータなし	入力を必要としないもの。
2.	単一文字列の入力パラメータ	定型アクションでパラメータ値を設定できる。（任意の文字列）
3.	事前定義した入力パラメータ（選択式）	予め定義されたリストの中から値を選択する。

定型アクションに表示するための必須項目がある

タスク定義に下記が含まれていないと定型アクションには表示されないので注意。

x-amzn-alexa-access-scope が public であること。
"info" に description が記載されていること。
"components" に x-amzn-display-details が追加されていること。さらに description が記載されていること。

Quick Links for Alexa 用にカスタムタスクを作ったときは、 description なしで良かったし、components に x-amzn-display-details の記載が無くても動作していた。しかし、そのスキルを定型アクションで指定しても、カスタムタスクの項目が現れる事はなかった。上記、Alexa カスタムタスクの実装と動作確認方法に記載されているタスク定義は定型アクションで使用するには不十分ということ。理由は、定型アクションの設定をする際の説明文として、description が使用されているため。このページの下部にある画像を見るとイメージが掴めると思う。

For each chosen locale, you must provide a user-friendly task title and task description in the task definition file, as the next step describes.
Note: If the task title and description for a given locale are missing from the task definition file, the task doesn't appear in Alexa routines for that locale.

追加①

info の x-amzn-display-details に description が必要。

    "info": {
      "title": "Task to get the campaign code",
      "version": "1",
      "x-amzn-alexa-access-scope": "public",
      "x-amzn-display-details": {
        "ja-JP": {
         "title": "キャンペーンコード",
         "description":"スキルに対して外部からキャンペーンコードを入力することができます。"   <- これ
        }
      }

定型アクションでスキルを選択すると、タスクの説明が表示される。

追加②

components にも x-amzn-display-details を記載する必要がある。

    "components": {
      "schemas": {
        "Input": {
          "type": "object",
          "properties": {
            "CampaignsCode": {
              "type": "string",
              "x-amzn-display-details":{        <- これ
                "ja-JP":{
                  "name": "キャンペーンコード",
                  "description":"キャンペーンコードを入力してください。"        <- これ
                }
              }

パラメータの入力時に説明が表示される。

スキル申請

申請時のエラーチェックに、カスタムタスクのエラーチェックが含まれるようになっているので、間違えはすぐ見つけられるようになっている。

審査にパスしないと試せない

カスタムタスクは審査にパスしないと使用することができない。不便である。そのため未テストの状態で申請に出さなければならない。動作もだけど、画面でどのような見栄えになっているかなどは、審査をパスした後でないと確認できない。審査後に文言等の修正が必要になった場合は、カスタムタスクの定義情報を修正して再申請する。

この前は、定義ファイルの修正だったためか、あっさり審査をパス。しかも土曜日の夜に申請して、日曜日の早朝には審査が通っていた。最速かも？

動きはこんな感じ

パラメータが入力できるようになっているのがわかると思います。Alexa活用の幅が広がりそう。

参考（カスタムタスク定義：単一文字列の入力パラメータ）

良く見たら、responses の description がいけてない・・・※修正漏れ。

{
    "openapi": "3.0.0",
    "info": {
      "title": "Task to get the campaign code",
      "version": "1",
      "x-amzn-alexa-access-scope": "public",
      "x-amzn-display-details": {
        "ja-JP": {
         "title": "キャンペーンコード",
         "description":"スキルに対して外部からキャンペーンコードを入力することができます。"
        }
      }
    },
    "tags": [{
      "name": "Campaignsc"
    }],
    "paths": {
      "/Campaigns": {
        "summary": "Campaigns Code",
        "description": "To start a campaign feature",
        "post": {
          "requestBody": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Input"
                },
                "examples": {
                  "GetCampaignsCode": {
                      "summary": "キャンペーンコードを取得",
                      "description": "キャンペーンコードを取得するためのタスク",
                      "value": {
                          "CampaignsCode": "Campaign A"
                      }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "When the count down finishes successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessfulResponse"
                  }
                }
              }
            },
            "400": {
              "description": "When the given parameters fail validations"
            },
            "500": {
              "description": "When the count down fails"
            }
          }
        }
      }
    },
    "components": {
      "schemas": {
        "Input": {
          "type": "object",
          "properties": {
            "CampaignsCode": {
              "type": "string",
              "x-amzn-display-details":{
                "ja-JP":{
                  "name": "キャンペーンコード",
                  "description":"キャンペーンコードを入力してください。"
                }
              }
            }
          }
        },
        "SuccessfulResponse": {
          "type": "object",
          "properties": {
            "endTime": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      }
    }
 }

参考（カスタムタスク定義：事前定義した入力パラメータ（選択式））

{
    "openapi": "3.0.0",
    "info": {
      "title": "Task to set the Egg size",
      "version": "1",
      "x-amzn-alexa-access-scope": "public",
      "x-amzn-display-details": {
        "ja-JP": {
         "title": "たまごのサイズを指定してゆでたまごタイマーを開く",
         "description":"サイズ指定を省略できるため、ゆでたまごタイマーを開くと同時にゆでたまごを作ることができます"
        }
      }
    },
    "tags": [{
      "name": "Egg size"
    }],
    "paths": {
      "/Eggsize": {
        "summary": "Egg size",
        "description": "たまごのサイズを設定することがでるカスタムタスクです。",
        "post": {
          "requestBody": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Input"
                },
                "examples": {
                  "SetEggsize": {
                      "summary": "たまごのサイズを指定",
                      "description": "あらかじめたまごのサイズを指定するためのタスクです。",
                      "value": {
                          "enumName": "M"
                      }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "When the egg size finishes successfully",
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessfulResponse"
                  }
                }
              }
            },
            "400": {
              "description": "When the given parameters fail validations"
            },
            "500": {
              "description": "When the egg size fails"
            }
          }
        }
      }
    },
    "components": {
      "schemas": {
        "Input": {
          "type": "object",
          "properties": {
            "enumName": {
              "type": "string",
              "enum": [
                "S","M","L"
              ],
              "x-amzn-display-details":{
                "ja-JP":{
                  "name": "たまごのサイズを選択",
                  "enums": {
                    "S":"Sサイズ（50g 前後）",
                    "M":"Mサイズ（60g 前後）",
                    "L":"Lサイズ（65g 前後）"
                  }
                }
              }
            }
          }
        },
        "SuccessfulResponse": {
          "type": "object",
          "properties": {
            "endTime": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      }
    }
 }

関連