Alexa Skills Toolkit for VS Codeでスキルを開発する (後編)

1 はじめに
2 Alexa Skills Toolkitの管理対象と管理方法
3 スキルパッケージ更新時の注意点
4 スキルパッケージの管理
5 スキルパッケージの更新とデプロイ
6 まとめ: 不整合を防ぐには
7 おわりに
8 参考情報
- - 8.0.1 変更履歴

はじめに

前編のクイックツアーで見た限りでは、VS Codeを使ったスキルの開発プロセスは、一見シンプルで特に注意点はなさそうに思えます。しかし前編の冒頭で述べたように、変更時の手順によっては、サーバー環境 (開発者コンソール) とローカル環境 (VS Code) の間に不整合が生じ、変更内容が失われるリスクが潜んでいます。本編ではどういう場合にそうした不整合が生じるのか、またどうしたら防げるのかを説明します。

Alexa Skills Toolkitの管理対象と管理方法

Alexa Skills Toolkit for VS Codeが管理する対象は、大きくスキルコードとスキルパッケージの２つになります。カッコ内はローカル環境でそれぞれが格納されているディレクトリです。

スキルコード (lambda)
- ソースコード
スキルパッケージ (skill-package)
- スキルマニフェスト
- 対話モデル
- APLドキュメント

どちらもサーバー環境 (開発者コンソール) と、ローカル環境 (VS Code) の何れでも更新が可能です。このため更新の仕方によっては、サーバー環境とローカル環境の間で、不整合が生じる場合があります。

これらの管理はGitで行われています。ソースコードについては、Git内で管理が完結しているため、ローカル環境とサーバー環境で不整合が生じたときには、Gitのpush/pull/mergeを駆使して対処できます。しかしスキルパッケージについては、Gitの外でも管理されており、ローカル環境とサーバー環境で不整合が生じた場合、その対処は少々複雑になります。

以下ではスキルパッケージの更新時の注意点を中心に説明します。

スキルパッケージ更新時の注意点

スキルパッケージをローカル環境で更新する場合、下記の3点に注意する必要があります。

ローカル環境で更新する前には、対象ファイルを必ずサーバー環境と同期 (ローカル環境を最新化) してから、更新を始める
ローカル環境で更新中は、同じものをサーバー環境で更新しない
ローカル環境で更新したものを、サーバー環境にデプロイする前には、更新対象以外のファイルも、サーバー環境と同期 (ローカル環境を最新化) する

#1, #2は当たり前と言えば当たり前です。スキルコードの場合は、Gitの機能を使ってローカル環境とサーバー環境の差分をマージすることも可能です。(もちろん避けたほうが良いですが …) しかしスキルパッケージについては、後述する理由でそれができません。両環境で同時に更新しないように注意が必要です。

#3は少し判り難いと思います。問題が生じるのは、例えばローカル環境でスキルマニフェストを更新し、同時にサーバー環境で対話モデルを更新するような状況です。

スキルマニフェストの項目には、サーバー環境の開発者コンソールでは設定できないものもあるので、そのような項目を設定する場合は、ローカル環境のVS Codeでの編集が必須になります。一方で対話モデルについては、VS CodeでJSONファイルを直接編集するよりも、開発者コンソールで編集する方が簡単です。

このような状況で、ローカル環境でスキルマニフェストの変更をコミットして、サーバー環境にデプロイしたとします。対話モデルはローカル環境では更新していませんから、影響を受けないはずです。しかし実際には、サーバー環境で行った対話モデルの変更が、古い内容で上書きされてしまいます。理由は後述しますが、これを避けるためには、ローカル環境の対話モデルを一旦サーバー環境と同期して、最新化しておく必要があります。

ここまでの説明を読まれて「よし判った」と思われた方は、この先の説明は不要かも知れません。(いや、保証はできませんが …) 「むむむ？なんのこっちゃ」となった方は、少し長くなりますが、この先の説明を読んでみてください。

スキルパッケージの管理

対話モデルのファイルja-JP.jsonを例に、スキルパッケージのファイルがどのように管理されているかを、下図に示します。サーバー環境の処理は筆者の推測です。外部から見える現象的には合っていると思いますが、実際の内部処理はこの通りではないかも知れません。

スキルマニフェスト、APLドキュメントのファイルについても、同様になります。

いくつか留意すべき点について以下に記します。

サーバー環境の変更はGitに反映されない

サーバー環境 (開発者コンソール) から行った変更はGitに反映されません。ローカル環境に反映するには、Git経由ではなく、ダウンロードやエクスポートの機能 (後述) を使います。

サーバー環境との不整合はGitでは検出も解消もできない

スキルパッケージはGitで管理されています。本来ならば、ローカル環境とサーバー環境の間でバージョンの不整合が起こった場合は、Gitがその不整合を検出してくれます。しかしサーバー側の更新がGitに反映されないため、Git上は不整合が検出できず、したがってその解消もできません。

デプロイするとサーバー環境での変更は上書きされる

ローカル環境からスキルパッケージをサーバー環境にデプロイすると、サーバー環境でビルドされます。このとき、Gitからスキルパッケージのファイルが取り出されてビルドされます。もしサーバー環境で行った変更があると、上書きされてしまいます。

これはローカル環境からデプロイするファイルだけでなく、それ以外のファイルにも適用されます。これにより、ローカル環境で変更していないファイルについても、古い内容で上書きされるという問題が生じます。

ローカル環境とサーバー環境の整合性はeTagで管理されている

サーバー環境とローカル環境のスキルパッケージの整合性は、eTagを使って管理されています。eTagはスキルパッケージのバージョンのようなもので、サーバー環境でスキルパッケージがビルドされるたびに、サーバー内で更新されます。このeTagはローカル環境にも同期されており、サーバー環境とローカル環境のeTagが一致しないと、不整合と見なされます。

ローカル環境のeTagは、下記の場合にのみサーバー環境と同期されます。

Deploy & build (又はForce deploy) でローカル側の更新がサーバー側に反映されたとき
Export skill packageでサーバー側の更新がローカル側に反映されたとき

これはeTagが同期していれば、ローカル環境のスキルパッケージは、最新のサーバー環境のスキルパッケージをベースにしている (同じかそこから更新されている) ことを意味します。

逆にeTagが同期していないと、サーバー環境と同期できておらず、ローカル環境からのデプロイでサーバー環境での変更が失われる恐れがあることを意味します。

注意すべきは、サーバー環境での変更を保存しただけでは、eTagは更新されないことです。このためローカル環境のAlexa Skills Toolkit for VS Code上では整合していると見なされていても、すでにサーバー環境では更新されている (変更が保存されている) 可能性があります。このため整合性を確認する前には、サーバー環境での変更に対してビルドしておく必要があります。

ダウンロードではeTagは更新されない

Alexa Skills Toolkit for VS Codeのメニューには、スキルマニフェスト、対話モデル、APLそれぞれにダウンロードのメニューがあります。このメニューからダウンロードした場合は、ローカル側のeTagの値は同期されません。eTagはスキルパッケージ全体の整合性を表しています。これに対してダウンロードは個別の項目に対して行えるため、ダウンロードだけでは全体の整合性を判定できないためと考えられます。

スキルパッケージの更新とデプロイ

スキルパッケージの更新とデプロイについて見ていきます。

以下の説明では、前編のスキルパッケージの更新状態を引き継いでいるものとします。具体的には、package.jsonとpackage-lock.jsonが更新されコミットされている状態です。

スキルのデプロイステータスの確認

まずスキルパッケージがどういう状態にあるかを確認します。

アクティビティで①Alexa Skills Kitを選び、メニューから②Deploy skillをクリックします。すると下図のような画面が表示され、スキルのデプロイステータスが確認できます。

③スキルのステータスの定義を下表に示します。ステータスはチェックマークとビックリマークで示されます。

項目	説明
Local Changes	デプロイ可能かどうかを示します。下記の場合に、デプロイ可能と判断されます。 (チェックマークが付く) – ローカル環境で更新されたファイルが全てGitでコミットされている、かつ – リモートにPushされていないものが残っているスキルコードとスキルパッケージの両方のファイルが対象です。前編の最終状態として、`package.json`, `package-lock.json`がコミットされているので、チェックマークが付いています。
Skill Package Remote Sync Status	ローカル環境のスキルパッケージとサーバー環境のスキルパッケージが同期しているかを示します。前述したように、eTagによって確認されます。
Skill Code Remote Sync Status	ローカル環境のスキルコードとサーバー環境のスキルコードのバージョンが同期しているか (ローカル環境のバージョンがサーバー環境と同じか新しい状態) を示します。Gitによって確認されます。

ローカル環境での更新が終われば、変更をコミットして、④Deploy & buildボタンをクリックして、サーバー環境を更新できます。しかし上記のステータスに不整合があると、該当項目にビックリマークが表示され、Deploy & buildボタンもForce deployボタンに変わります。

どういう場合に不整合が生じるのか、不整合が生じたときはどうすれば良いのか、このあとに見ていきます。

スキルパッケージの更新

サーバー環境での更新の例として、対話モデルを更新してみます。スキルマニフェスト、APLドキュメントの場合も考え方は同じです。

アクティビティで①Alexa Skills Toolkitを選び、メニューから②Interaction model>Edit in consoleをクリックします。

Webブラウザで開発者コンソールが開きます。

ビルドタブでインテントから①HelloWorldIntentを選び、②サンプル発話にこんにちはを追加します。③モデルをビルドをクリックし、④【完全ビルドが完了しました】というメッセージが表示されたら対話モデルの更新が完了です。

この状態でVS Codeに戻り、アクティビティから①Alexa Skills Toolkitを選びます。メニューから②Deploy skillをクリックし、【Skill deploy and build】の画面が開いたら、③Refresh to update the statusアイコンをクリックします。結果、下図のような内容が表示されます。

【Skill Package Remote Sync Status】に④ビックリマークがついています。これはサーバー環境のスキルパッケージとローカル環境のスキルパッケージの間に、バージョンの不整合があることを示しています。具体的には、サーバー環境の対話モデルが更新されて、ローカル環境よりも新しくなっているためです。

ここで⑤Force deployボタンは決して押さないでください。古い対話モデルで、先程更新したサーバー環境の対話モデルが上書きされてしまいます。

この状態の解消方法は、次の【不整合の解消方法】で説明します。

不整合の解消方法

不整合が発生するのは、サーバー環境の開発者コンソールからスキルパッケージのビルドが行われた場合です。

この不整合を解消するには、以下の２つの方法があります。

Force deployによる方法
サーバー環境で変更されたファイルを、個別にローカル環境にダウンロードします。その後 (ローカル環境での更新とコミットの後に) 強制的にデプロイします。
Export skill packageによる方法
サーバー環境のファイルを、まとめてダウンロードします。ローカル環境で更新中のものがない場合は、この方法が一番簡単です。

Force deployによる方法

ASK技術ドキュメントには、対話モデルを開発者コンソールで更新したあとの処理について、下記のように書かれています。

アクティビティバーで、Alexaアイコンをクリックします。Alexa Skills Toolkitサイドバーが表示されます。
Skills、スキル、Interaction Modelの順に展開し、Downloadを選択します。Download latest interaction modelページが表示されます。
正しいロケールを選択し、Downloadをクリックします。

これを実行してみます。アクティビティから①Alexa Skills Toolkitを選び、メニューから②Interaction model>Downloadをクリックします。下図の画面が表示されるので、Localeで③Japanese (JP)を選び、④Downloadボタンをクリックします。

対話モデルja-JP.jsonがダウンロードされ、VS Codeのエディタで開かれます。そのまま保存してください。

アクティビティから①Alexa Skills Toolkitを選び、メニューから①Deploy skillをクリックします。【Skill deploy and build】のパネルが開きます。②Refresh to update the statusアイコンをクリックしてステータスを更新します。結果、下図のような内容が表示されます。

【Local Changes】に④ビックリマークが付いているのは、ダウンロードされた対話モデルのファイルが、コミットされていないからです。これはあとでコミットすることで消えます。

問題は【Skill Package Remote Sync Status】が相変わらず⑤ビックリマークのままだということです。これはダウンロードしただけでは、eTagが同期されないからです。

次にダウンロードした対話モデルをコミットします。(add . は手抜きですが …)

git add .
git commit -m "対話モデル更新"

VS Codeのアクティビティで①Alexa Skills Toolkitを選び、メニューから②Deploy skillをクリックします。【Skill deploy and build】の画面が表示されたら、③Refresh to update the statusアイコンをクリックします。結果、下図のような内容が表示されます。

先程のコミットにより④【Local Changes】の不整合は消えましたが、⑤【Skill Package Remote Sync Status】の不整合は残っています。しかし実際には対話モデルのファイルをダウンロードしたので、ローカル環境はすでに全て (対話モデル以外も含めて) 最新になっています。つまり強制的にデプロイしても問題ありません。

もし対話モデル以外にも開発者コンソールで更新されたものがあれば、それらもダウンロードして、保存、コミットしておいてください。

ここで⑥Force deployボタンをクリックします。

下図のように確認が求められるので、Confirm force deployをクリックします。

“Skill deployment in progress”の表示が出たあと、しばらくすると画面が切り替わり、下図のように”Skill build succeedded”の表示が確認できます。

再びアクティビティで①Alexa Skills Toolkitを選び、メニューから②Deploy skillをクリックします。【Skill deploy and build】の画面が表示されたら、③Refresh to update the statusアイコンをクリックします。結果、下図のような内容が表示されます。

デプロイすべき変更はなく、【Skill Package Remote Sync Status】, 【Skill Code Remote Sync Status】ともに同期されていることが判ります。

ダウンロード時の注意点

サーバー環境での対話モデルの変更は、保存しただけの状態だと、ダウンロードには反映されません。ダウンロードされるのはビルドされたあとのものです。APLドキュメントの変更も同様です。スキルマニフェストは、変更が保存されていればダウンロードに反映されます。

「あれ？対話モデルの変更をダウンロードしたのに反映されていない」と思ったら、ビルドしたかどうか確認してください。

Export skill packageによる方法

もう一度、開発者コンソールで対話モデルを更新してビルドした直後に話を戻します。

このときVS Codeの【Skill deploy and build】の画面には、「同期問題を解決」するために、下記のように2つの方法が書かれています。

To solve the sync issue, you can Export skill package to download the remote version, or commit local changes and force deploy the skill.

先程行ったのは、この２番目の”force deploy the skill”に該当します。これに対して、ここでは１番目の”Export skill package”を行います。

Export skill packageのリンクをクリックします。下図のように警告がでますが、Yesをクリックします。この時点でローカルで更新されたものはないので、上書きされても構わないからです。

もしローカルで更新したものがあれば、Noをクリックして中止してください。対話モデルだけでなく、スキルマニフェストやAPLドキュメントに対する更新も含みます。その場合は、【Force deployによる方法】に従う必要があります。

Exportが完了すると下図の画面が表示されます。

【Skill Package Remote Sync Status】, 【Skill Code Remote Sync Status】ともに同期されていることが判ります。エクスポートされたファイルはコミットされていないため、【Local Changes】にはビックリマークが付いています。次の変更サイクルの中で、これらもコミットしてDeploy & buildを行えば同期が完了します。