Alexaスキルから定型アクションが設定できるようになる。まだ英語版のみ。

キーワード

定型アクション（routines）
カスタムタスク（custom task）
スキルコネクション（skill connections）

前提条件

Developer Preview（2022年12月時点）
カスタムスキルであること。
英語ロケールのみ。（en-US、en-CA、en-IN、en-GB、en-AU）　※日本はまだ使えない
子供向けスキルまたはHIPAAスキルでは使用できない。

定義できる定型アクションの条件

トリガーが１つ含まれていること。
最大２つまでのアクションを設定できる。
アクションが１つの場合、launch skill action または custom task action を使用してアクションを実行する必要がある。
アクションが２つの場合、最初のアクションはAmazon-defined actionで、スキルの実行は２番目のアクションに設定する必要がある。

トリガー

日本版の定型アクションには、Sunrise、Sunsetは存在しないですね。どんな動きをするんでしょうかね。

No	トリガー	type名
1	Custom utterance trigger 音声	Alexa.Automation.Trigger.Voice.CustomUtterance
2	Time/schedule trigger スケジュール	Alexa.Automation.Trigger.Schedule.AbsoluteTime
3	Sunrise/sunset trigger 日の出、日の入り	Alexa.Automation.Trigger.Schedule.Sunrise Alexa.Automation.Trigger.Schedule.Sunset

アクション

予めAmazonで定義されたアクション Amazon-defined と、スキル定義のアクション Skill-defined とがある。Amazon定義のアクションは必須ではない。

No	種類	アクション	type名
1	Amazon-defined	Announcement action アナウンスを送信？	Alexa.Automation.Operation.Notification.Notify
2	Amazon-defined	Date action 日付と時刻	Alexa.Automation.Operation.Time.PlayWhatDate
3	Amazon-defined	Time action 日付と時刻	Alexa.Automation.Operation.Time.PlayWhatTime
4	Amazon-defined	Weather action 天気	Alexa.Automation.Operation.Weather.PlayForecast
5	Amazon-defined	Flash briefing ニュース	Alexa.Automation.Operation.News.PlayFlashBriefing
6	Skill-defined	Launch skill action スキル	Alexa.Automation.Operation.Skill.Launch
7	Skill-defined	Custom task action スキル	Alexa.Automation.Operation.Skill.StartConnection

実装の流れ

1. （任意）カスタムタスクをスキルに追加する。

カスタムタスクを使ってスキルを起動させる場合は、まずスキルにカスタムタスクを追加しておきましょう。
Alexa 定型アクションでカスタムタスクを使って自分のスキルを起動させる方法 -Custom Task with Alexa Routines-

2. 定型アクションをデザインする。

Pre-Built Routines は、１つのトリガーと最大２つのオペレーションで構成できるので、どんなアクションにするかを考える。

・発話されたらスキルを起動する。
・時刻になったら、天気を言ってからスキルを起動する。
ほか・・・

3. 定型アクションを設定するコードを追加する。

Pre-Built Routines はスキルコネクションの機能を利用して、ユーザーのAlexaアプリに定型アクションを設定する仕組み。

responseBuilder に .addDirective を追加する。

  return handlerInput.responseBuilder
    .speak('何か言う')
    .addDirective( <ここに Pre-Built Routines の定義を記載する> )
    .getResponse();

Connections.StartConnection ディレクティブで AMAZON.OfferAutomation を使用する。
詳しくはリファレンスを参照する。

{
  type: "Connections.StartConnection",
  uri: "connection://AMAZON.OfferAutomation/1",
  input: {
    automation: {
      trigger: {
        type: "Alexa.Automation.Trigger.Voice.CustomUtterance",
        version: "1.0",
        payload: {
          utterances: ["utterance A", "utterance B", "utterance C"],
          locale: "en-US"
        }
      },
      operations: {
        operation: {
          type: "Alexa.Automation.Operation.Skill.Launch",
          version: "1.0",
            payload: {
              skillId: "amzn1.ask.skill.190effea-2563-48f6-a3ae-6cfe50ec69f0"
            }
          }
        }
      }
    },
    onCompletion: "RESUME_SESSION",
    token: "example-token"
  }
}

4. テストする

音声を使って、スキルコネクションに遷移が渡るか、定型アクションが設定されたか、ステータスコードは正しいかを確認する。

5. 指標を取得する

SMAPIを使うとPre-Built Routines のオファーに対するユーザーの反応に関するメトリクスを取得できるらしい。

ask smapi get-skill-metrics

(SMAPI) Get metrics

LWAのトークンを取得するときに、SCOPE を注意する必要がある。このSCOPEがないとMetricsが取得できない。

ask util generate-lwa-tokens --scopes "alexa::ask:skills:readwrite alexa::ask:models:readwrite"

その他

１つのアカウントに重複登録はできない

結果オブジェクト（リクエストタイプ：SessionResumedRequest）には templateId が含まれている。一度、定型アクションが生成されると、templateId が設定され、次に登録しようとすると、status.code : 204が返されるようだ。

  "status": {
    "code": "200",
    "message": "Automation successfully enabled"
  },
  "result": {
    "offerAutomationResponse": {
      "templateId": <テンプレートID>
    }
  }

再オファーの間隔

ユーザーがオファーを拒否した場合は、少なくとも 7日間はあけること。

ユーザー側でのステータスはわからない

スキルの操作中に定型アクションが有効になった後、その定型アクションのステータスは共有されない。オファーを出して、templateId があるかないかぐらいしかわからないようだ。

定型アクションの更新

新しい定型アクションを追加する場合は、再認定が必要。

おわりに

やりとりが煩わしくならないようにデザインを考える必要はあるが、スキルから定型アクションが設定できるのはとても良いと思う。早く日本語版でも使えるようになって欲しい。これは開発者にとっては良い機能だと思う。