ローカルでAlexaスキルをデバッグする環境をセットアップする

Toshimi Hatanaka Jul 20, 2020
Share:
Advanced Node.js Tutorial
Blog_Header_Post_Img

AlexaスキルをAlexa-hostedやAWS Lambda上にホスティングしている場合、リモート環境でデバッグする必要があります。リモート環境のデバッグ作業では、CloudWatch Logsのコンソールにアクセスしてエラーログを解析したり、コードを修正するたびにデプロイし直す必要があるため、作業がはかどらないことが多いのではないでしょうか?

今回のブログ記事では、公開されているデバッグ用のスクリプトや、プロキシソリューションを利用してローカルでデバッグできる環境をセットアップすることで、スキル開発をスピードアップする方法をご紹介します。

ローカルデバッグ環境をセットアップすると、手元にあるコードを使ってデバッグすることができるため、スキルの修正/テストの繰り返し作業を効率よく行うことができるようになります。

このブログでは、Node.js を例に解説します。Pythonのデバッグについては、guide for debugging with Pythonを、Javaのデバッグについては、guide for debugging for Java ガイドを参照してください。

 

ローカルデバッグ環境のセットアップ

既にスキルがリモートにホストされた状態にある場合は、スキルのコードをローカルにクローンするところから始めましょう。スキルコードのクローンにはASKコマンドラインインターフェース(ASK CLI)を利用します。

ASK CLIを使ったことがない方は、クイックスタート: Alexa Skills Kitコマンドラインインターフェース(ASK CLI) を参照してください。このブログでは、ASK CLI v2 を前提に説明します。

 

ステップ1 ローカル環境にスキルのプロジェクトファイルを作成する

スキルがAWSにホストされている場合

AWS Lambdaにホストされるスキルコードをローカルマシンにクローンするには、AWS Lambdaからスキルコードをエクスポートします。スキルコードをダウンロードしたら、プロジェクトディレクトリ内で ask init コマンドを実行してAlexaのスキルパッケージリソースをダウンロードし、ASK CLI v2を使ったデプロイ用にプロジェクトをセットアップします。スキルマニフェスト(skill.json)、対話モデルも取得したい場合は、サブコマンドget-interaction-modelget-skill-manifestを使用してください。 smapiサブコマンドの詳細はASK CLIコマンドリファレンスを参照してください。

 

スキルがAlexa-hosted 環境にホストされている場合

スキルがAlexa-hosted環境にホストされている場合は、ask init --hosted-skill-id コマンドを実行するだけで、現在のディレクトリに<スキルID>で指定したスキルのクローンが作成されます。

Copied to clipboard
$ ask init --hosted-skill-id <スキルID>

スキルIDは、Alexa開発者コンソールのエンドポイントの画面に記載されています。これをコピーして使用してください。

Skill ID

注意: ASK CLI v1 (以下v1と表記)を使ってデプロイしたスキルは、上記のv2のコマンドではクローンできません。v1 を使ってデプロイされたスキルは、ask util upgrade-projectコマンドを使って、v2形式にアップグレードしておく必要があります。詳しくはASK CLI v1からv2への移行ガイドを参照してください。

 

ローカルマシンで新しくスキルを作成する場合

ASK CLI(v2)を使ってこれから新しいスキルを作成する場合は、コマンドラインでask new コマンドを実行します。コマンドを実行すると、対話形式で開発に使用する言語、スキルのバックエンドリソースをホストする方法、スキル名、プロジェクトフォルダーの名前などが聞かれます。お好みで選択してください。

 

ステップ2 デバッグ用スクリプトをダウンロードする

ローカルのスキルコードをコールするために、デバッグ用スクリプトを利用します。Node.js用のスクリプトをダウンロードして、スキルのプロジェクトディレクトリのルートに配置します。ファイル名はlocal-debugger.js のままにしておきます。

Localdebugger.js file location

ステップ3 Alexaのリクエストをスキルに転送する

通常、AlexaはAWS Lambdaなどにホストされているスキルコードにリクエストを送信しますが、ローカル環境でスキルをデバッグするには、Alexaのリクエストをローカルコンピュータに転送する必要があります。これにはプロキシサービスを利用します。いくつか選択肢はありますが、ここでは最もお手軽なサードパーティのサービス ngrok を使用することにします。以下のリンクからご自身の環境にあった ngrok のバイナリをダウンロードしてください。

ngrok のダウンロードができたら、任意の空きポートを使って ngrok プロキシに接続します。この例では3001番のポートを使用して ngrok を起動しています。

Copied to clipboard
$ ngrok http 3001

注意: ngrokの有料プランに登録していない場合、プロキシーサービスのセッションは8時間で終了します。

次に、ngrok の出力に表示される https転送アドレス(Forwardingと書かれている項目)をコピーします。

launch ngrok

Alexa開発者コンソールを開き、開発中スキルの[ビルド]タブをクリックします。左パネルの[エンドポイント]をクリックします。

次に、エンドポイントの種類で「HTTPS」を選択します。先ほどコピーした転送URLを「デフォルトの地域」のフィールドにペーストします。

「SSL証明書の種類を選択」のオプションは「開発者用のエンドポイントは、証明機関が発行したワイルドカード証明書を持つドメインのサブドメインです」を設定します。

custom endpoint

設定が完了したら「エンドポイントを保存」ボタンをクリックします。

これで Alexa のリクエストは ngrok を通してローカル環境に転送されるようになりました。

補足:もしエンドポイントを変更した際にエラーが発生して設定できない、または設定が反映されない場合は、ステップ6の方法で元に戻すことができます。

 

ローカルのエンドポイントを、スキルマニフェストファイル(skill.json)で指定する場合

スキルマニフェストファイルskill.jsonでローカルのエンドポイントを指定するには、次のように修正してください。

  • sourceDir 属性にLambda関数のパスを設定
  • uri 属性に ngrok の Forwarding URL を設定
  • sslCertificateType 属性に Wildcard を設定

Copied to clipboard
{
  "manifest": {
    "publishingInformation": {
     ...
    },
    "apis": {
      "custom": {
        "endpoint": {
          "sourceDir": "lambda",
          "uri": "https://abc123.ngrok.io",
          "sslCertificateType": "Wildcard"
        }
      }
    },
    "manifestVersion": "1.0"
  }
}

マニフェストの更新には、プロジェクトフォルダーのルートの位置で ask deploy コマンドを使用します。

Copied to clipboard
$ ask deploy

スキルがAlexa-hosted にホストされている場合は、Gitコマンドを使って更新することができます。

Copied to clipboard
$ git add skill-package/skill.json
$ git commit -m <コメント>
$ git push origin master

ステップ4 デバッガーを起動する

Visual Studi Code(以下VSCode)を使ってスキルコードをデバッグするには、スキルのプロジェクトに設定を追加します。VSCodeのメニューから「実行」>「構成の追加...」を選択して、環境の選択リストから「node.js」を選択します。

setup debugger
select nodejs

すると、プロジェクトフォルダー内に .vscode/launch.json ファイルが作成され編集画面が開きます。

launch.png

以下の内容をコピーして、launch.jsonファイルの内容を全て上書きしてください。

Copied to clipboard
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "program": "${workspaceRoot}/local-debugger.js",
            "args": [
                "--portNumber", "3001",
                "--skillEntryFile", "${workspaceRoot}/lambda/custom/index.js",
                "--lambdaHandler", "handler"
            ],
        }
    ]
}

launch.json の以下の項目は、ご自身の環境に合わせて修正を行ってください。

  • program の項目に local-debugger.js ファイルをのパスを指定
  • --skillEntryFile のオプションに、Lambdaハンドラーファイル(通常はindex.js)のパスを指定

これで VSCodeでデバッグを開始する準備ができました。VSCodeのメニューから「実行」>「デバッグの開始」を選択してデバッガーを起動します。すると、下図のように VSCode がデバッグモードに切り替わります。

launch debugger

ブレイクポイントは、コードの行番号の左横をクリックすると簡単に設定または解除することができます。任意の場所にブレイクポイントを設定できますが、まずは試しにLaunchRequestHanderhandle() メソッドあたりにブレイクポイントをつけておくと良いでしょう。

set breakpoint

ステップ5 スキルを呼び出してデバッグを開始する

Alexa開発者コンソールの「テスト」タブを開き、テスト環境のモードを「開発中」に変更します。

development mode

コマンドラインでは、以下のsmapiサブコマンドを使って同様のことができます。

Copied to clipboard
$ ask smapi set-skill-enablement -s <スキルID>

それでは、Alexaシミュレーターを使ってスキルを呼び出して起動してみましょう。スキルの起動は、タイプ入力するか、パソコンのマイクで入力するか、同じ開発者アカウントでセットアップされたEchoデバイスを使っても構いません。

スキルが起動すると、Alexaから送信される全てのリクエストはローカル環境に転送され、あらかじめ設定しておいたブレイクポイントの位置で処理が一時停止します。この時点でのAlexaから送信されたリクエスト(JSON)の内容や、変数の値、コールされた関数のスタック履歴などの情報を確認することができます。

debugging with VSCode

これで、コードを修正するたびにデプロイし直したり、ブラウザを開いてCloudWatch Logsでログを解析する必要がなくなり、快適にデバッグ作業ができるようになりましたね。

注意: Alexaサービスは8秒以内にスキルからレスポンスが返ってくることを要求します。ブレイクポイントで停止中に8秒以上経過した場合、Alexaサービスとのセッションが終了します。デバッグを続けたい場合は、スキルを起動するとこらからやり直す必要があります。

 

ステップ6 エンドポイントを元の設定に戻す

ローカル環境でのデバッグが完了したら、リモート環境に戻しましょう。

Alexa-Hostedスキルを使用している場合、Alexa開発者コンソールの「コードエディタ」タブをクリックすると、下のようなアラートが表示されています。右の「Use Alexa hosted endpoint」をクリックすることで、簡単に元の状態に戻すことができます。

Revert to remote endpoint

AWS Lambdaにホストしている場合は、エンドポイントの設定を元のARNの設定に戻せばOKです。

ARN Endpoint

ASK CLIを使ってAWSにデプロイした場合は、マニフェストファイル(skill.json)で元のエンドポイントに戻したあと、ask deployコマンドでデプロイしなおしてください。

 

まとめ

スキル開発プロセスにローカルデバッグ環境をセットアップすることで、スキルのデバッグにかかる時間を大幅に短縮することができます。コードを修正するたびにデプロイする時間を待たされたり、CloudWatch Logsの出力を解析してどこで問題が発生したかを検索したりするストレスから開放され作業効率が向上します。

是非、このテクニックをお試してみてください。

よりスピーディにテストとデバッグ作業を反復して行うことで、結果的により品質の高いスキルを作っていただけることを期待しております。