Alexaスキルから定型アクションを設定する - Pre-Built Routines -


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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/426739/5059c509-830a-16c1-3638-c277366c3f3b.png)


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

# 前提条件

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


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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/426739/ebac5112-33a1-bcdf-bb63-dce6eef1ec36.png)

##### トリガー

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

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

##### アクション

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

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


# 実装の流れ

#####  1. <font color="OrangeRed">（任意）</font> カスタムタスクをスキルに追加する。

カスタムタスクを使ってスキルを起動させる場合は、まずスキルにカスタムタスクを追加しておきましょう。
:point_right:[Alexa 定型アクションでカスタムタスクを使って自分のスキルを起動させる方法 -Custom Task with Alexa Routines-](https://qiita.com/takara328/items/fe51465946864b103048)

##### 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](https://developer.amazon.com/en-US/docs/alexa/smapi/metrics-api.html#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` があるかないかぐらいしかわからないようだ。

##### 定型アクションの更新

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



# おわりに

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