Alexa-HostedスキルをASK CLIで開発するときの注意点

はじめに

Alexa-Hostedスキルを、ASK CLI (Alexa Skills Kit – Command Line Interface)を使って開発する時の注意点を紹介します。

ASK CLIはAlexaスキルをローカル環境で開発できる便利なツールです。しかし、実際の開発ではサーバー環境の開発者コンソールとローカル環境の両方で作業が発生し、最悪の場合は一方の更新が他方の更新で上書きされる可能性があります。

このためASK CLIと開発者コンソールが、どのように成果物を管理・更新しているのか、調査しました。それを元に開発作業に適用すべき利用指針（というには大げさですが）をまとめました。

更新プロセスの説明（推測）に紙幅を費やしていますが、先に結論を知りたい方はこちらを御覧ください。

ベストプラクティスは

いきなりですが、もしベストプラクティスはと聞かれると、

「もしあなたがVisual Studio Code (VS Code)のユーザーなら、ExtensionのAlexa Skills Kit (ASK) Tookitを使いましょう」

と答えます。「CLIじゃ無いじゃないか」と言われてしまいそうですが、あれこれ試行錯誤してみた結果としては、ASK Toolkitの利用が一番問題が少ないようです。

とは言うものの、ASK Toolkitの利用にも注意点はあります。また筆者のようにコマンドラインでの操作が好みの人もいるでしょう。ここではCLIとしての利用を前提に、注意点をまとめてみました。

Alexa Skills Kit (ASK) Toolkitを使った開発については別途紹介したいと考えています。

ASK Toolkitを使った開発については、下記の記事を御覧ください。

• Alexa Skills Kit (ASK) ToolkitとVS Codeでスキルを開発する（前編）
• Alexa Skills Kit (ASK) ToolkitとVS Codeでスキルを開発する（前編）

ASK CLIの管理対象

Alexa-Hostedスキルを作成すると、初期状態では下記の成果物が作成されます。

├── ask-resources.json
├── lambda/
│   ├── index.js
│   ├── package.json
│   └── util.js
└── skill-package/
    ├── interactionModels/
    │   └── custom/
    │       └── ja-JP.json
    └── skill.json

この中でASK CLIで管理する成果物は大きく以下の２つに分かれます。

• ソースコード（lambda）
• スキルパッケージ (skill-package)

これらの成果物は、何れもGitプロジェクトとして管理されますが、ソースコードとスキルパッケージでは、その管理の仕方に違いがあります。

Gitレポジトリの構成

成果物を入れるレポジトリは、AWS CodeCommitで管理されています。AWSクラウド上で提供されるGitベースのサービスです。クライアント側ではGitツールが使えます。

このレポジトリには、dev, master, prodの３つのブランチが切られています。ローカル環境には、そのうちmaster, prodの２つのブランチが、チェックアウトされています。ローカル環境でのデフォルトはmasterブランチです。またmaster, prodはそれぞれDevelopment, Liveのステージ（実行環境）と紐付けられています。

ソースコードの管理

ソースコードはGitレポジトリの中で管理されています。index.jsを例に、Gitレポジトリの中でどの様に管理されているか、概要を下図に示します（筆者による推測を含む）。

ソースコードの管理はシンプルです。Gitのオペレーションに慣れていれば、特に問題はないはずです。

ローカル環境での更新

下記のステップでDevelopmentステージのコードを更新できます。

1. U: ローカル環境のmasterブランチでソースコードを更新
2. U: commit/pushの操作でサーバーのmasterブランチに反映
3. S: サーバーのdevブランチにmerge
4. S: Developmentステージに反映

U – ユーザー
S – システム (Alexa)

下記のステップでLiveステージのコードを更新できます。このコードの更新は、スキルの再認定を受ける必要がありません。

1. U: ローカル環境のmasterブランチでソースコードを更新（そしてDevelopmentステージでテスト）
2. U: ローカル環境をprodブランチに変更
3. U: masterブランチの変更をprodブランチにmerge
4. U: commit/pushの操作でサーバーのprodブランチに反映
5. S: Liveステージに反映

開発者コンソールでの更新

開発者コンソールでは、ソースコードを変更した後、保存、デプロイ、公開の３つの操作ができます（公開はスキルが公開済みの場合のみ可能）。

下記のステップでDevelopmentステージのコードを更新できます。

1. U: 開発者コンソールで変更を保存
2. S: サーバーのdevブランチにcommit
3. U: 開発者コンソールで変更をデプロイ
4. S: サーバーのmasterブランチにmerge
5. S: Developmentステージに反映

下記のステップでProductionステージのコードを更新できます。

1. U: 開発者コンソールで変更を公開
2. S: サーバーのprodブランチにcommit
3. S: Liveステージに反映

コンフリクトの解消

Gitのpush/pullで対応できます。

ローカル環境での更新は、Gitのcommit/pushを通してサーバー環境に反映します。

開発者コンソールでの更新は、Gitのpullを通してローカル環境に反映します。このとき開発者コンソールでは、デプロイまで実行しておきます。そうしないと、devブランチとmasterブランチで違いができてしまい、あとでmerge作業が必要になるからです。

スキルパッケージの管理

スキルパッケージには、スキルマニフェスト（./skill-package/skill.json）と、対話モデル（./skill-package/interactionModels/custom/ja-JP.json）が含まれています。これらもソースコード同様にGitレポジトリの中で管理されますが、その更新のプロセスは少し異なります。

skill.jsonを例に、Gitレポジトリの中でどの様に管理されているか、概要を下図に示します（筆者による推測を含む）。 対話モデル（ja-JP.json）の場合も同じです。以下の説明のスキルマニフェストを対話モデルと読み替えてください。

ソースコードの場合と違い、開発者コンソールでの更新がGitに反映されません。このためローカル環境での更新と開発者コンソールでの更新が、コンフリクトを起こす可能性があり、注意が必要です。これについては後述します。

ローカル環境での更新

下記のステップでDevelopmentステージのスキルバッケージを更新できます。

1. U: ローカル環境のmasterブランチでスキルマニフェストを更新
2. U: commit/pushの操作でサーバーのmasterブランチに反映
3. S: サーバーのmasterブランチの内容を使ってビルドを実行
4. S: Developmentステージに反映

注意が必要なのは、#3, #4のステップです。ビルド時にはスキルマニフェストだけでなく、対話モデルもmasterブランチから取得されます。もし開発者コンソールで対話モデルを更新していた場合は、Gitからの古い内容で上書きされてしまいます。これについては、この後のコンフリクトの解消で詳しく述べます。

ソースコードと違って、スキルマニフェストが直接Liveステージに反映されることはありません。必ず認定審査を経て反映されます。

開発者コンソールでの更新

開発者コンソールからは、スキルのアクセス権限の設定などで、スキルマニフェストを更新する場合があります。

1. U: 開発者コンソールで変更を保存 (例: アクセス権限)
2. S: ビルドを実行
3. S: Developmentステージに反映

ソースコードとの違いは、更新結果がGitには反映されないことです。開発者コンソールから見えている対話モデルの内容は、Gitとは別の領域で管理されているようです。

コンフリクトの解消

開発者コンソールでの更新がGitに反映されないため、開発者コンソールでの更新後にローカル環境を更新してGitからcommit/pushすると、開発者コンソールでの更新が上書きされてしまいます。

これを避けるためには、開発者コンソールで管理している最新のスキルマニフェストをダウンロードして、ローカル環境のスキルマニフェストを更新する必要があります。下記のコマンドでダウンロードできます。スキルIDは、開発者コンソールのスキル一覧の画面から取得できます。

ask smapi get-skill-manifest -s {skill id}

同じく対話モデルの場合は下記になります。（ロケールは日本語を仮定しています）

ask smapi get-interaction-model -l ja-JP -s {skill id}

ビルド中に上書きされるのは、変更されたスキルマニフェストだけではないことに注意が必要です。対話モデルも上書きされる可能性があります。このためスキルマニフェストをローカル環境で更新する時には、スキルマニフェストと対話モデルの両方を最新化しておく必要があります。同じことは、対話モデルを更新する場合にも当てはまります。

ASK CLI利用時の指針

筆者の場合は、下記のような指針で対応しています。

• ソースコード
  • 常にローカル環境で更新し、Gitでサーバー環境にpushします。
  • もし開発者コンソールで更新した場合は、Gitでローカル環境にpullします。
• 対話モデル
  • 常に開発者コンソールで更新します。スロットなどを使うと定義内容が複雑になり、JSONファイルの直接編集は困難だからです。
• スキルマニフェスト
  • 基本は開発者コンソールで更新します。
  • 設定項目の中には開発者コンソールからは定義できない項目があり、その場合はローカル環境で更新し、サーバー環境にGitでpushします。
    • ローカル環境で更新する前には、対話モデルとスキルマニフェストの両方をサーバー環境からダウンロードして最新化します。
    • スキルマニフェストは、対話モデルと違って頻繁に更新するものでは無いので、更新の必要なときだけ、一時的に上記のステップを踏むようにしています。

スキルマニフェストの更新時に、対話モデルの最新化を忘れないでください。もし忘れると対話モデルが古い内容で上書きされてしまい、悲惨な結果となります。

問題が発生するシナリオ

参考までに、上書きが発生するシナリオについて記述します。

下記のシナリオでは、開発者コンソールで対話モデルを変更した後に、ローカル環境でスキルマニフェストを変更しています。この変更をサーバーにpushすると、サーバー環境でビルドのプロセスが走り、Gitに保管されていたオリジナルの対話モデルが使われます。このため開発者コンソールから行った対話モデルへの変更が失われます。

• 初期状態

• ローカル環境でソースコード（index.js）を更新してpush
• スキルパッケージのビルドは発生せず

• 開発者コンソールで対話モデル（ja-JP.json）を更新
• スキルパッケージをビルド
• Gitからは更新されないため問題は発生せず

• ローカル環境でスキルマニフェスト（skill.json）を更新してpush
• スキルパッケージをビルド
• Gitから更新されるため問題発生
  • 対話モデル（ja-JP.json）がV1からV0に戻る

おわりに

Alexa-Hostedスキルを、ASK CLI (Alexa Skills Kit – Command Line Interface)を使って開発する時の注意点を紹介しました。

裏で動いている仕組みが判ってしまえば（判ったつもりになれば？）、それほど難しいことではありませんし、不用意な操作で変更を上書きするといった、不幸な事故も避けられるのではと思います。

参考情報

• ASK CLIを使用したAlexa-hostedスキルの作成と管理
• ASK CLIコマンドリファレンス (v2)

更新記録