※このブログは、Greg Bulmash のブログをToshimi Hatanakaが日本向けに翻訳し加筆修正したものです。
SMAPI SDKを使用すると、サポートされているプログラミング言語（Node.js、Python、Java）のいずれか を使用して、Web、モバイル、デスクトップアプリ上にAlexaスキルの管理やレポート機能をこれまで以上に簡単に組み込むことができるようになります。
Alexaスキル管理API（SMAPI）は、あなたのスキルに対して、Alexa Skills Kit の コマンドラインインターフェース（ASK CLI） やAlexa開発者コンソールでできることを、RESTベース のAPIで提供するものです。実際、ASK CLIやAlexa開発者コンソールの機能の多くはSMAPI を利用して作られています。今回、 Alexa SMAPI SDKが正式にリリースされ、コードから簡単にスキル管理APIを利用できるようになりました。このブログ記事では、Alexa Cookbook SMAPI SDKのデモで公開されている Node.js 用のサンプルコードを見ながら、Alexa SMAPI SDK を利用するためのヒントをご紹介します。
まずはセットアップから始めましょう。この記事と同じようにデモを試したい場合は、 GithubのAlexa Cookbookからサンプルコードをダウンロードしてください。
README.mdファイル（Github.comまたはダウンロードしたディレクトリで読むことができます）には、認証情報やベンダーIDの取得方法など、サンプルコードのセットアップに必要な情報が記載されています。
セットアップ時のヒント: Login with Amazon のセキュリティプロファイルを作成する際、 もしくは既存のプロファイルを使用する際、セキュリティプロファイルの画面の「ウェブ設定」タブを開き、「許可された返信URL」のフィールドに「http://127.0.0.1:9090/cb」を入力してください。こうすることで、ASK CLIを通してSMAPI SDKで利用する認証情報を受け取ることができます。 この方法は、ローカルコンピュータで実行するCLIコマンドの出力にトークンを表示させるためのデモ用の設定ですが、ローカルコンピュータ上で動作するコードがトークンを取得する方法のヒントにもなるでしょう。
GitHub.com のREADME.md の手順に従ってアクセストークン(およびリフレッシュトーク ン)を取得する際、 ask util generate-lwa-tokens コマンドに --client-id と --crient-confirmation のオプションを追加し、クライアントIDとシークレット を明示的に指定してください。
$ ask util generate-lwa-tokens --client-id <クライアントID> --client-con firmation <クライアントシークレット>上記のコマンドを実行すると、WEBブラウザが開き、開発者アカウントでのログイン（認証）が求められます。ログインが完了すると、下の図のようなアクセス許可を求める（認可）画面が表示されます。ここでは「許可」ボタンをクリックします。
コマンドラインの出力には、アクセストークンとリフレッシュトークンが表示されます。これらをコピーしてサンプルコード内で利用します。
もしあなたが、複数のAmazon開発者アカウントを使用するコードを書こうとしていて、かつ全てのユーザーにCLIを実行させることが難しい場合、 アプリの中でセキュリティプロファイルとAlexaスコープを使ってLogin with Amazonとアプリのコードを統合することで、 ユーザーに代わってトークンを取得することができます。
Alexa Coockbook のサンプルコードは、SMAPI SDK for node.js の「Getting Started」のインストラクションに記載されている SMAPI クライアントを作成して利用する手順とほぼ同じです。
- SDK をインポート
- 複数のコードから認証情報を取得しやすいように分離した tokens.js から認証情報オブジェクトをインポート
- Node.js の “util” パッケージをインポート
- “refreshTokenConfig” オブジェクトの作成
- SMAPI クライアントを作成
// Import the sdk
const Alexa = require('ask-smapi-sdk');
// Import your authentication info
const Token = require('./tokens.js');
// And the util library will make for more readable output
const util = require('util');
// specify the refreshTokenConfig with clientId and clientSecret
// from your Login with Amazon client config
// and access/refresh tokens generated via the ASK CLI
const refreshTokenConfig = {
"clientId": Token.client_Id,
"clientSecret": Token.client_Secret,
"refreshToken": Token.refresh_token,
"accessToken": Token.access_token
}
//build the SMAPI client
const smapiClient = new Alexa.StandardSmapiClientBuilder()
.withRefreshTokenConfig(refreshTokenConfig)
.client();
どちらのサンプルコードも上のコードで始まります。tokens.js に認証情報が正しく設定されていれば、listSkills.js は全く編集することなくそのまま実行することができます。
// This retrieves a list of the skills associated with
// your vendorId. You can use that info for other demos.
smapiClient.listSkillsForVendorV1(Token.vendorId)
.then((response) => {
console.log(util.inspect(response, {"showHidden":false, "depth":4, "colors": true, "compact": false}));
})
.catch((err) => {
console.log(err.message);
console.log(util.inspect(err, {"showHidden":false, "depth":4, "colors": true, "compact": false}));;
});
コマンドラインから node listSkills.js を実行すると、以下のようなJSONが表示されます(表示は一部省略しています)。
サンプルコードは、簡単に動作を確認できるように簡略化してあります。Vendor ID を取得するには、Alexa開発者コンソールからVendor IDを手作業で取得する方法もありますが、 smapiClient.getVendorListV1() メソッドを使うと、指定したアカウントに紐づくVendor ID の配列を取得することができます。そこから必要なVendor IDを選択して利用することも可能です。
次に getMetics.js のコードを見てみましょう。ここでは多くのことができるので、レポートデータを取得するSDKの処理は、分割しておくとよいでしょう。
以下が、メインの部分の関数呼び出しです。
smapiClient.getSkillMetricsV1(
'[skill ID]',
'[start date/time]',
'[end date/time]',
'[Period]',
'[metric]',
'[stage]',
'[type]'
)
GetSkillMetricsV1のメソッドは、レポートAPIの技術文書のどこにも載っていないため、それがどういうものなのか、すぐにはわからないかもしれません。 実は、このメソッドの名前は、対応する「操作名」と「API バージョン」の組み合わせでできていて、監査ログAPI の技術文書の「操作名とサポートされているバージョン 」の表を見れば分かるようになっています。
使用したいSDKのSMAPI関数を、最も簡単に探すには、段使用しているコードエディタの自動補完機能を利用するとよいでしょう(もしその機能があればですが)。Visual Studio Codeの例を見てみましょう。
コードの冒頭で、 smapiClient 変数を定義した後、 smapiClient. と入力します (最後にピリオドをタイプすることに注意してください)。そうすると、次に続いて利用可能なメソッドとプロパティのリストが表示されます。ピリオドの後に何か文字をタイプすると、リストが絞り込まれ、 smapiClient.metrics に続いて、 getSkillMetricsV1 と callGetSkillMetricsV1 の2つの選択肢が表示されます。
これらは基本的には同じメソッドですが、最初に call が付いているメソッドは、APIと HTTPとの変換についてより多くの情報を返し、そうでないメソッドは結果だけを返します。
どちらか一つを選択して、最初の括弧 "(" を入力します。すると関数に必要な引数のリストが表示されます。
getSkillMetricsV1(skillId: string, startTime: string, endTime: string, period: string, metric: string, stage: string, skillType: string, intent?: string, locale?: string, maxResults?: number, nextToken?: string): Promise<v1.skill.metrics.GetMetricDataResponse>名前の後に「?(クエスチョンマーク)」が付いている引数はオプションです。このメソッ ドの引数の詳細については、レポートAPIの技術文書の「リクエストのパラメーター」の表を参照してください。
サンプルコードでは、引数に好みの値を代入すると、選択したスキルに関するレポート情報の出力を得ることができます。
SMAPI SDK は、開発者自身が使うツールや、ユーザーが利用するアプリケーションに Alexa SMAPIがサポートする機能を組み込む際に役立ちます。開発者のみなさまが、 SMAPI API を利用して、どのようなツールやアプリケーションを構築するかとても楽しみです。
ASK CLI v2.0 正式リリース。スキルリソースの効率的な管理とタスクの自動化
