Alexa Skills KitコマンドラインインターフェースとAlexaスキル管理APIの概要



Alexa Skills Kitコマンドラインインターフェース(ASK CLI)の概要

Alexa Skills Kitコマンドラインインターフェース(ASK CLI)を使用すると、ほとんどのAlexaスキルのタスクをコマンドラインから実行できます。ASK CLIは、次の用途で使用します。

  • スキルの新規作成
  • スキルの対話モデルの更新とビルド
  • スキルのAlexa-hostedスキルまたはAWSへのデプロイ
  • スキルのシミュレーション
  • スキルの認定および公開のための申請

ASK CLIをダウンロードしてインストールするには、ASK CLIクイックスタートを参照してください。

新しいスキルプロジェクトを作成する

新しいスキルを作成するには、ask newを実行します。実行すると、スキルをコーディングする言語を選択するようプロンプトが出ます。

$ ask new
? Choose the programming language you will use to code your skill
  - Node.js
  - Python
  - Java

次に、スキルのバックエンドコードのホスティングプロバイダーを選択します。ASK CLIは、次のホスティングプロバイダーへのデプロイをサポートしています。

ホスティングプロバイダー                          説明
Alexa-hostedスキル アカウントで新しいスキルを作成し、スキル用の無料のホスティングを利用できます。スキルコードを実行するAWS Lambda関数、メディアストレージ用のAWS S3バケット、AWS CodeCommitリポジトリが含まれます。
AWS CloudFormation AWSアカウントが必要です。 AWS CloudFormationのスターターテンプレートを含む新しいスキルプロジェクトを作成します。ASK CLIは、このテンプレートを使ってLambda関数やS3バケットといったスキルのホスティングに必要なAWSリソースをプロビジョニングします。
AWS Lambda AWSアカウントが必要です。 スキルコードを直接AWS Lambda関数にデプロイする新しいスキルプロジェクトを作成します。

独自にスキルのホスティングを管理することもできます。AWSアカウントをお持ちでない場合は、Alexa-hostedスキルの使用をお勧めします。

? Choose a method to host your skill's backend code
- Alexa-Hosted
Host your skill code with Alexa (free)
- AWS with CloudFormation
Host your skill code with AWS and provision with CloudFormation (requires AWS account)
- AWS Lambda
Host your skill code on AWS Lambda (requires AWS account)
- Self-Hosted
Manage your own hosting

選択したホスティングオプションによっては、スキルのスターターテンプレートを選択する必要があります。

? Choose a template to start with
- Hello world		  Alexa's hello world skill to send the greetings to the world!
- Fact skill		  Quick sample skill to manage a collection of voice data.
- High low game		Guess a number high or low using persistent attributes.

最後に、スキルの名前とローカルプロジェクト名を指定します。

? Please type in your skill name:  マイスキル
? Please type in your folder name for the skill project (alphanumeric):  my-skill-project

コマンドを実行すると、現在のディレクトリに新しいスキルプロジェクトが作成されます。

独自のカスタムスキルテンプレートを使って新しいスキルを作成することもできます。カスタムテンプレートを使うには、--template-urlでテンプレートのGit URLを指定します。

$ ask new --template-url https://example.com/example/example-skill.git

スキルプロジェクトの構造

ASK CLIでAlexaスキルテンプレートを使ってプロジェクトを作成すると、デフォルトでは、プロジェクトに次のファイルやフォルダが含まれます。

プロジェクトファイルまたはフォルダ                         目的
skill-package/ スキルのマニフェスト、関連する対話モデル、スキル内商品、画像アセットなどのスキルパッケージリソースが含まれます。
infrastructure/ AWS CloudFormationでデプロイする場合、スキルのCloudFormationテンプレートはこのフォルダに入ります。
lambda/ スキルのバックエンドソースコードが含まれています。
ask-resources.json ASK CLIがスキルのデプロイに使用するJSON設定ファイルです。

スキルをデプロイする

Gitを使ってAlexa-hostedスキルをデプロイする

Alexa-hostedスキルを作成した場合は、Gitを使ってスキルをデプロイします。

git pushコマンドを実行し、ローカルリポジトリのmasterブランチから、Alexa-hostedスキルのあるリモートリポジトリ(通常はorigin)のmasterブランチにコードをプッシュします。

$ git push origin master

このコマンドは、最後に確定したバージョンをAlexa-hostedスキルにデプロイする場合に使用します。変更をプッシュすると、Alexa-hostedスキルはスキルパッケージリソースとリモートのmasterからのバックエンドのスキルコードの両方をデプロイします。Alexa-hostedスキルは、リモートのmasterブランチにプッシュするコードのみをデプロイします。

AWS CloudFormationを使ってデプロイする

CloudFormationデプロイ用に設定したスキルには、デフォルトでは、スキルプロジェクトのinfrastructure/ディレクトリにskill-stack.yamlという名前のCloudFormationのスターターテンプレートが入ります。このCloudFormationテンプレートを更新して、スキルにAWSリソースを追加します。CloudFormationの詳細については、AWS CloudFormation の使用開始を参照してください。

スキルをデプロイする準備ができたら、次のコマンドを実行します。

$ ask deploy

ASK CLIは、次のアクションを実行してスキルをデプロイします。

  1. スキルパッケージAPIを使って、スキルのskill-package/ディレクトリのコンテンツをパッケージ化し、Alexaスキルにアップロードします。そのスキルを初めてデプロイした場合、このコマンドを実行すると、設定したAmazon開発者アカウントに新しいスキルが作成されます。
  2. スキルコードをlambda/ディレクトリでビルドし、デプロイのビルドアーティファクトをAWSにパッケージ化します。これには、スキルの依存関係のインストールとビルドアーティファクトの生成が含まれます。Node.jsで記述されたスキルの場合、npm installを実行してpackage.jsonで宣言された依存関係をインストールし、JavaScriptソースコードでパッケージ化します。
  3. ビルドアーティファクトとinfrastructure/ディレクトリの下にあるCloudFormationテンプレート(デフォルトのテンプレート名はskill-stack.yaml)を、設定したAWSアカウントで作成したS3バケットにアップロードします。
  4. AWS CloudFormationを呼び出して、アップロードしたCloudFormationテンプレートで定義したAWSリソースをプロビジョニングします。S3にアップロードしたビルドアーティファクトもプロビジョニングしたLambda関数にデプロイされます。

AWS Lambdaにデプロイする

AWS Lambda用に設定したスキルをデプロイするには、次のコマンドを実行します。

$ ask deploy

ASK CLIは、次のアクションを実行してスキルをデプロイします。

  1. スキルパッケージAPIを使って、スキルのskill-package/ディレクトリのコンテンツをパッケージ化し、Alexaスキルにアップロードします。そのスキルをまだデプロイしていない場合、このコマンドを実行すると、設定したAmazon開発者アカウントに新しいスキルとして作成されます。
  2. スキルコードをlambda/ディレクトリでビルドし、デプロイのビルドアーティファクトをAWSにパッケージ化します。これには、スキルの依存関係のインストールとビルドアーティファクトの生成が含まれます。Node.jsで記述されたスキルの場合、npm installを実行してpackage.jsonで宣言された依存関係をインストールし、JavaScriptソースコードでパッケージ化します。
  3. ビルドアーティファクトを設定したAWS Lambda関数にデプロイします。このスキルのデプロイが初めてで、まだLambda ARNが設定されていない場合、このコマンドにより新しいLambda関数が作成されます。

Gitからビルドアーティファクトを除外する方法

AWSをデプロイすると、ASK CLIは.ask/ディレクトリの下にビルドアーティファクトを生成します。これらのアーティファクトをGitから除外するには、スキルプロジェクトの.gitignore.ask/を追加します。

スキルをテストする

コマンドラインからスキルをテストするには、ask dialogを実行して、スキルでサポートするロケールを指定します。

$ ask dialog --locale ja-JP

このコマンドにより、Alexaとのマルチターンの会話をシミュレートできる対話型のターミナルが開きます。

============================== Welcome to ASK Dialog ===============================
=== In interactive mode, type your utterance text onto the console and hit enter ===
============= Alexa will then evaluate your input and give a response! =============

User  > ハローワールドを開いて
Alexa > ようこそ。こんにちは、または、ヘルプ、と言ってみてください。どうぞ!
User  > ヘルプ
Alexa > こんにちは、と言ってみてください。 どうぞ!
User  > こんにちは
Alexa > ハローワールド
User  > .record <path_to_replay_file>
Created replay file at <path_to_replay_file>
User  > .quit

================================= Goodbye! =========================================

dialogコマンドの詳細については、ask dialogのリファレンスを参照してください。

SMAPIを使ってスキルリソースを管理する

AlexaスキルをASK CLI、SMAPIのいずれかで管理する場合は、特定のスキルリソースに対応するJSONスキーマを使用します。詳細については、次のページを参照してください。

チーム開発のベストプラクティス

アカウント管理

ASK CLIは、OAuth 2.0標準に準拠したAuthorization Code grantアプローチを使用します。ASK CLIはクライアント側のツールのため、アクセストークンの取得に使用する更新トークンのセキュリティを確保する責任は開発者にあります。チームでスキル開発を行う際にセキュリティを適切に確保するには、特に注意が必要です。チームで同じチームアカウントを共有する場合には更新トークンの漏洩が起こりやすくなるからです。

ベンダーのオーナーアカウントを所有するチームリーダーは、共有していないユーザーアカウントを持つことをお勧めします。他の開発者のアクセスは、ベンダーへのメンバー登録によって管理します。また、各開発者にもそれぞれ固有のユーザーアカウントを持たせるようにしてください。このアプローチでは、チーム内の権限を厳密に定義し、公開された場合には更新トークンを無効にします。

複数ユーザーが1つのアカウントを管理する場合の詳細については、Amazon開発者アカウントと権限を管理するを参照してください。

不正利用されたアカウント

アカウントが不正に利用された可能性がある場合、状況に応じて以下のソリューションに従ってください。

必要な措置と手順

  • 更新トークンをすべて取り消す: Your Account>Manage Login with Amazonを開き、アプリケーションを削除します。アプリケーションを削除すると、チームがASK CLIに保存した更新トークンは無効になります。期限が切れていないアクセストークンは引き続き有効です。次回Login with Amazonで認証を行うと、Login with Amazonはスコープを再度付与し、ASK CLIアプリケーションをもう一度作成するようプロンプトを出します。

  • Amazonアカウントのパスワードをリセットする: パスワードをリセットしたら、すべての更新トークンを取り消す手順に従い、ASK CLIに保存した更新トークンを無効にします。