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



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

Alexa Skills Kitコマンドラインインターフェース(ASK CLI)は、Alexaスキル、対話モデルやアカウントリンクの詳細といった関連リソースをコマンドラインから管理するために使用できるツールです。対話形式やスクリプトでの利用はもちろん、コマンドライン実行ステップをサポートする開発システム、継続的インテグレーション、継続的デプロイメントを行う製品と統合することもできます。ASK CLIは、Alexaスキル管理APIを呼び出すことで、スキル管理アクションを実行できます。ASK CLIは、Alexaスキルや接続しているAWS Lambda関数の作成、読み込み、更新、テストに使用できます。また、スキル認定の申請や取り消しも実行できます。

ASK CLIで開発を始める

ASK CLIは、JavaScriptのパッケージマネージャーであるnpmを使ってインストールできます。詳細については、ASK CLIクイックスタートを参照してください。

ASK CLIを使うと、さまざまなタスクのうち、次をコマンドラインで実行できます。

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

ask newコマンドを使って、テンプレートからコピーすることで新しいスキルプロジェクトを作成します。Amazonが提供するテンプレートのいずれかを使うか、独自のテンプレートを指定することができます。

構文のリファレンスについては、ASK CLIコマンドリファレンスのask newを参照してください。

Amazonが提供するテンプレートを使う

パラメーターなしでask newを実行すると、新しいスキルのランタイムを選択するようASK CLIのプロンプトが表示され、Amazonが提供するスキルテンプレートのリストが一覧表示されます。これらのテンプレートには、基本的なスキルに必要なファイルとフォルダーがすべて含まれています。ask newコマンドは、これらのファイルとフォルダーをコンピューターにコピーし、スキルプロジェクトフォルダーに保存します。スキルプロジェクトフォルダーを参照してスキルのしくみを理解したり、アカウントの開発中ステージに(ask deployコマンドを使用して)スキルをデプロイすることもできます。これらのテンプレートをスキルを作成する足掛かりとして活用してください。

Amazonが提供するテンプレートには、ASK CLIによってトリガーされるスクリプトであるフックも含まれています。これらのスクリプトはローカルで実行され、スキルのランタイム環境のセットアップに有効です。詳細については、フックを参照してください。

スキルプロジェクトフォルダーの構造

Amazonが提供するテンプレートのいずれかから新しいスキルプロジェクトを作成すると、スキルプロジェクトには以下のファイルやフォルダーが作成されます。

スキルプロジェクトフォルダー
|-- .ask
    |-- config
|-- hooks
    |-- post_new_hook
    |-- pre_deploy_hook
|-- lambda
    |-- Lambda関数のソースコードファイル
|-- models
    |-- JSONファイル(ロケールごとに1つ、対話モデルを含む(ja-JP.jsonなど)
|-- skill.json

スキルプロジェクトは次のように構成されています。

  • .ask – ASK CLIのconfigファイルを含む非表示のフォルダーです。
  • hooks – フックスクリプトを含むフォルダーです。Amazonでは、post_new_hookpre_deploy_hookという2つのフックを提供しています。
  • lambda – スキルのAWS Lambda関数のソースコードを含むフォルダーです。ここに含まれるファイルはスキルのランタイムによって異なります。
  • models – スキルの対話モデルを1つ以上含むフォルダーです。各対話モデルは、ロケール名の付いたJSONファイルで定義されます。たとえば、en-US.jsonde-DE.jsonなどです。
  • skill.json – スキルマニフェストを含むファイルです。

Amazonが提供するテンプレートを使って新しいスキルを作成する

  1. パラメーターなしでask newコマンドを使用します。プロンプトが出たら、ランタイムを選択します。矢印キーを使ってリスト内を移動し、Enterキーを押して強調表示されたオプションを選択します。
    C:\> ask new
    ? Please select the runtime (Use arrow keys)
    > Node.js V8
      Python3
    
  2. Amazonが提供するテンプレートを1つ選択します。矢印キーを使ってリスト内を移動し、Enterキーを押して強調表示されたオプションを選択します。
    C:\> ask new
    ? Please select the runtime Node.js V8
    ? List of templates you can choose (Use arrow keys)
    > Hello World
      Buttons ColorChanger
      City Guide
      Decision Tree
      Fact
      Feed
      Foodie
    (Move up and down to reveal more choices)
    
  3. スキル名を入力するか、Enterキーを押してデフォルト名を使用します。ASK CLIはこの名前を使用して、コンピューターにスキルプロジェクトフォルダーを作成します。
    C:\> ask new
    ? Please select the runtime Node.js V8
    ? List of templates you can choose Hello World
    ? Please type in your new skill name, alphanumeric only: skill-sample-nodejs-hello-world
    Skill skill-sample-nodejs-hello-world has been created based on the chosen template
    

ASK CLIはスキルプロジェクトフォルダーを作成し、選択したスキルテンプレートからすべてのファイルとフォルダーを追加します。ASK CLIはhooksフォルダーのpost newフックスクリプトを実行します。詳細については、フックを参照してください。

独自のテンプレートを使う

Amazonが提供するテンプレートから選択する代わりに、独自のスキルテンプレートを使うことができます。独自のテンプレートを使うには、以下のいずれかのURLを指定します。

独自のスキルテンプレートを使うには、Gitをインストールしておく必要があります。詳細については、GitのドキュメントでGitのインストールを参照してください。

Gitリポジトリからのテンプレートを使う

Gitリポジトリからのスキルテンプレートを使うには、--urlパラメーターでGitのURLを提供します。以下の例を参照してください。

C:\> ask new --url https://example.com/example/example-skill.git
? Please type in your new skill name, alphanumeric only: example-skill
[Warn]: Downloading skill template from unofficial resource.Please make sure you understand what each script is doing to best protect yourself from malicious usage
? Would you still like to continue execution ? Yes
Skill example-skill has been created based on the chosen template

この例では、ASK CLIがスキル名の入力を求めるプロンプトを表示しています。--skill-name-nのパラメーターを使ってスキル名を提供できます。

テンプレートのリストを使う

テンプレートリストからのテンプレートを使うには、テンプレートリストを含むJSONファイルのURLを提供します。JSONファイルには、それぞれに対応するGit URLが指定されたテンプレート名のリストが含まれる必要があります。JSONファイルの形式の例については、Amazonが提供するスキルテンプレートのJSONファイルを参照してください。

--urlパラメーターでJSON URLを提供します。以下の例を参照してください。

C:\> ask new --url https://example.com/example/templates/example-templates.json
? List of templates you can choose Example Skill
? Please type in your new skill name, alphanumeric only: example-skill
Skill example-skill has been created based on the chosen template

リストに複数のテンプレートが含まれる場合、ASK CLIはテンプレートを選択するようプロンプトを出すので、スキル名を入力します。--templateパラメーターでテンプレート名を提供し、--skill-nameまたは-nパラメーターでスキル名を提供することもできます。

スキルプロジェクトを開発中ステージにデプロイする

ask deployコマンドを使って、新規または更新したスキルプロジェクトをデプロイします。スキルプロジェクトには以下が含まれます。

  • スキルマニフェスト(skill.jsonファイル)
  • 1つ以上のスキルモデル
  • スキルのAWS Lambda関数のソースコードとコンフィギュレーション
  • (日本未対応)1つ以上のスキル内商品

構文のリファレンスについては、ASK CLIコマンドリファレンスのask deployを参照してください。

新しいスキルをデプロイする

ローカルのスキルプロジェクトをデプロイしたことがない場合、ASK CLIはアカウントの開発中ステージに新しいスキルを作成してからスキルプロジェクトをデプロイします。該当する場合、ASK CLIは1つ以上の新しいAWS Lambda関数をAWSアカウントに作成し、Lambda関数のコードをアップロードします。具体的には、ASK CLIは以下を実行します。

  1. スキルプロジェクトのconfigファイル(スキルプロジェクトフォルダーの.askフォルダー内)に既存スキルIDがあるかどうかを確認します。configファイルにスキルIDがない場合、ASK CLIはスキルプロジェクトのskill.jsonファイルのスキルマニフェストを使用して新しいスキルを作成してから、スキルIDをスキルプロジェクトのconfigファイルに追加します。
  2. スキルプロジェクトのマニフェスト(skill.jsonファイル)でスキルを公開したロケールを確認します。これらのロケールは、manifest.publishingInformation.localesオブジェクトにリストされています。各ロケールについて、ASK CLIはスキルプロジェクトのmodelsフォルダーの対応するモデルファイル(en-US.jsonなど)を確認し、そのモデルをスキルにアップロードします。ASK CLIはアップロードされたモデルがビルドされるのを待ってから、各モデルのeTagをスキルプロジェクトのconfigファイルに追加します。
  3. スキルプロジェクトのマニフェスト(skill.jsonファイル)でAWS Lambdaエンドポイントを確認します。これらのエンドポイントは、manifest.apis.<skill type>.endpointまたはmanifest.apis.<skill type>.regions.<region code>.endpointオブジェクト(manifest.apis.custom.endpointまたはmanifest.apis.smartHome.regions.NA.endpointなど)にリストされています。各endpointオブジェクトにはsourceDir値と、任意でuri値が含まれています。ASK CLIはsourceDirフォルダーの中身を対応するAWS Lambda関数にアップロードし、Lambda関数をuri値と同じ名前にします。ASK CLIのLambdaへのアップロード方法の詳細については、AWS Lambdaのデプロイの詳細を参照してください。
  4. スキルプロジェクトフォルダーでスキル内商品を確認し、見つかった場合は、それらをスキルにアップロードします。スキル内商品の詳細については、スキル内課金の概要を参照してください。

更新したスキルをデプロイする

ローカルのスキルプロジェクトを前にデプロイしたことがある場合(スキルプロジェクトのconfigファイル(スキルプロジェクトフォルダーの.askフォルダー内)にスキルIDが存在することにより判断される)、ASK CLIは既存のスキルを更新します。まず、ASK CLIは、以下のようにローカルのスキルプロジェクトをアカウントの開発中ステージにあるスキルと比較し、違いを判断します。

ASK CLIでローカルのスキルプロジェクトとデプロイしたスキルの間の違いを比べるには、それぞれのスキルリソースのeTagを比較します。違いがある場合、ASK CLIは以下の警告を表示します。

-------------------- Update Skill Project --------------------
[Error]: The local stored [skill] eTag does not match the one on the server side.
   Use "ask diff" to inspect the difference between local and remote.
   Use "ask deploy --force" to deploy with the local project version regardless of the eTag.

ローカルのスキルとデプロイしたスキルのeTag値に違いがない場合、または--forceパラメーター(ask deploy --force)を指定した場合、ASK CLIは通常、新しいスキルをデプロイするセクションに記載したのと同じ方法でスキルをデプロイします。

AWS Lambdaのデプロイの詳細

新しいLambda関数を作成するとき、ASK CLIはAWSLambdaBasicExecutionRoleを関数に関連付けます。詳細については、AWS Lambdaドキュメントのアクセス権限の管理: IAMロール(実行ロール)を使用するを参照してください。ASK CLIで使用するよう設定したAWS認証情報にIAMロールを作成する権限があることを確認して、権限を関連付けます。

Lambda関数を作成してデプロイするとき、ASK CLIはスキルプロジェクトのconfigファイル(スキルプロジェクトフォルダーの.askフォルダー内)を確認して使用するランタイムとハンドラーを判断します。これらの値は、deploy_settings.default.resources.lambda.runtimedeploy_settings.default.resources.lambda.handlerのフィールドにあります。deploy_settings.default.resources.lambdaは配列のため、 runtimehandlerのフィールドは複数ある場合があります。configファイルにランタイムとハンドラーがなかった場合、ASK CLIはランタイムのデフォルト値として「Node.js 8.10」を、ハンドラーのデフォルト値として「index.handler」を使います。

ASK CLIは、Lambda関数を作成またはデプロイするAWSの地域を判断するのに、スキルプロジェクトのマニフェスト(skill.jsonファイル)でAWS Lambdaエンドポイントを確認します。これらのエンドポイントは、manifest.apis.<skill type>.endpoint(デフォルトのエンドポイント)またはmanifest.apis.<skill type>.regions.<region code>.endpointオブジェクト(地域固有のエンドポイント)にリストされています。ASK CLIでは、使用するAWS地域を決定する際、以下のルールに従います。

ASKリージョンコードAWSリージョンコードAWSリージョン名
デフォルトまたはNAus-east-1米国東部(バージニア北部)
EUまたはINeu-west-1EU(アイルランド)
FEus-west-2米国西部(オレゴン)

新しいLambda関数を作成するか、既存の関数を更新するかを判断する際、ASK CLIはスキルプロジェクトのマニフェスト(skill.jsonファイル)で各endpointオブジェクトのuri値を確認します。ASK CLIは、ASKリージョンコード(前述の表を参照)とuri値を組み合わせて、uri値と同じ名前の既存Lambda関数を検索します。見つかった場合、ASK CLIは既存のLambda関数を更新します。見つからなかった場合、新規に作成します。スキルプロジェクトのマニフェストにuri値がない場合、ASK CLIはスキルプロジェクトのconfigファイル(.askフォルダー内)にある情報を使って新規作成します。

ASK CLIで作成または更新するLambda関数の名前をカスタマイズするには、スキルプロジェクトのマニフェスト(skill.jsonファイル)の各endpointオブジェクトにあるuri値を変更します。場合によっては、ASK CLIがLambda関数名にuri値を使わないことがあります。これは、旧バージョンのASK CLIとmergeフィールドを含むスキルプロジェクトのconfigファイル(.askフォルダー内)を使った場合です。この場合、スキルプロジェクトのconfigファイルでmergeフィールドを削除することをお勧めします。

フック

フックは、ASK CLIによってトリガーされるスクリプトです。ASK CLIでは以下の2つのフックがサポートされています。

  • ask newコマンドの最後に自動で実行されるpost newフックです。
  • ask deployコマンドの最初に自動で実行されるpre deploy hookです。

Amazonが提供するフックは、スキルのランタイム環境のセットアップに有効です。以下のセクションでは、Amazonが提供するフックが実行することASK CLIがフックを実行するタイミングASK CLIがスキルプロジェクトにフックを追加するタイミングについて説明します。

Amazonが提供するフックが実行すること

Amazonが提供するフックは、スキルのランタイム環境のセットアップに有効です。詳細はスキルのランタイムによって異なります。

Node.jsスキルの場合、post newとpre deployのフックは同じ結果です。各スクリプトは以下を実行します。

  1. スキルプロジェクトディレクトリのskill.jsonファイルで、ソースディレクトリを確認します。これらはsourceDir要素で指定されています。
  2. 各ソースディレクトリに対して、npm installを実行してpackage.jsonファイルに記載されている依存関係をソースディレクトリにインストールします。依存関係は、ソースディレクトリのnode_modulesフォルダーにインストールされます。

各スクリプトのソースを確認するには、以下のリンクを参照してください。

Pythonスキルの場合、post newフックは以下を実行します。

  1. スキルプロジェクトディレクトリのskill.jsonファイルで、ソースディレクトリを確認します。これらはsourceDir要素で指定されています。
  2. 各ソースディレクトリに対して、venvまたはvirtualenvを使用してPythonの仮想環境を作成します。
  3. 仮想環境で、pipを実行してrequirements.txtに記載されている依存関係をソースディレクトリにインストールします。依存関係は仮想環境にインストールされます。

post newフックのソースを確認するには、以下のリンクを参照してください。

pre deployフックは以下を実行します。

  1. スキルプロジェクトディレクトリのskill.jsonファイルで、ソースディレクトリを確認します。これらはsourceDir要素で指定されています。
  2. 各ソースディレクトリに対して、lambda_uploadと言う名前のフォルダーを作成します。
  3. ソースコードをソースディレクトリからlambda_uploadフォルダーにコピーします。
  4. 依存関係を仮想環境からlambda_uploadフォルダーにコピーします。
  5. skill.jsonファイルの関連するsourceDir値でlambda_uploadフォルダーを更新します。

pre deployスクリプトのソースを確認するには、以下のリンクを参照してください。

ASK CLIがフックを実行するタイミング

ASK CLIはpost newフックをask newコマンドの最後に実行し、pre deployフックをask deployコマンドの最初に実行します。これらのコマンドは、スキルプロジェクトフォルダーのhooksを検索し、post_new_hookask newが実行)とpre_deploy_hookask deployが実行)というスクリプトファイルを実行します。hooksフォルダーが見つからない場合、コマンドがフォルダーを作成し、その後Amazonが提供するフックをダウンロードします。詳細については、ASK CLIがフックを追加するタイミングAmazonが提供するフックが実行することを参照してください。

ASK CLIがフックを追加するタイミング

ASK CLIは、以下のタイミングでスキルプロジェクトフォルダーのhooksフォルダーを検索します。

  • ask newコマンドの最後
  • ask cloneコマンドの最後
  • ask deployコマンドの最初

hooksフォルダーがない場合、ASK CLIはAmazonが提供するフックをダウンロードします。詳細については、Amazonが提供するフックが実行することを参照してください。

オブジェクトスキーマ

AlexaスキルをASK CLIまたはSMAPIで管理する場合、各リソースをJSON形式で表記する必要があります。詳細については、次のページを参照してください。

開発者のチームでスキルを開発する

ASK CLIを使うと、開発者のチームでのスキル開発が容易になります。これについては以下のセクションで説明しています。

チームアカウント管理のベストプラクティス

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にすでに保存されている更新トークンはすべて削除されます。