Alexaスキル開発トレーニングシリーズ 第5回 アカウントリンクとホームカード機能

このトレーニングは6回のシリーズで、Alexaスキルの基礎、仕組み、スキルの開発と認証まで、幅広い内容を解説します。 第5回では、Alexaスキルと外部のWebシステムとの連携に利用するアカウントリンクとホームカード機能について学習します。(第1回、第2回、第3回、第4回の記事もご覧ください)

1. AlexaスキルによるOAuth2連携
2.  (参考) ホームカードの利用
3. 実習 : サンプルスキルへの処理の追加

まずは、今回学習する内容を簡単に説明するビデオを見てみましょう。

5-1. AlexaスキルによるOAuth2連携

Alexaスキルと外部のWebサービスとの連携は、既存のWebサービスに音声による新たなインターフェースを追加する、大きな可能性を秘めています。たとえば通信販売のWebシステムと連携し、以下のような注文スキルが実現できます。

 

ユーザー : 「アレクサ、通販で洗剤を注文して」

Alexa : 「洗剤の注文ですね。いくつ注文しますか」

ユーザー : 「1個」

Alexa : 「洗剤を1個注文しました」(連携するWebサービスに洗剤1個の注文リクエストを送信)

 

一方で、通信販売のユーザーが注文するリクエストを不特定多数のユーザーが呼び出すAlexaスキルで行うためには、誰から注文がリクエストされたのかを適切に識別し、スキルとWebシステムとの情報のやり取りを安全に行う仕組みが必要です。ASK (Alexa Skills Kit) ではそれらを実現するために、インターネット標準の認証・認可方式であるOAuth 2.0をサポートします。この機能のことをアカウントリンクと呼びます。

 

アカウントリンクは、ユーザーがAlexaアプリからWebサービスにログインし、ユーザーに代わってAlexaスキルが目的のWebサービスにアクセスすることを許可するよう設定します。

Alexaスキル側では、WebサービスのログインページのURLなどをあらかじめ設定し、以下の順でWebサービスと連携します。

 

1. アカウントリンクによってAlexaサービスは連携するWebサービスの認証・認可サーバーからアクセストークンを取得します。
2. Alexaサービスは、Lambda関数にリクエストを送信する際に、目的のWebサービスへアクセスするためのユーザーのアクセストークンを含めます。
3. アクセストークンを用いてLambda関数からWebサービスへのリクエストを発行します。
4. Lambda関数でWebサービスからのレスポンスを取得します。

 

ここでのポイントは、スキルを呼び出したユーザーとアカウントリンクを設定したWebサービスの組み合わせをAlexaサービスが管理している点にあります。同じスキルを呼び出す他のユーザーにアクセストークンが渡ることを防ぎ、またスキル開発者はWebサービスとの連携をプログラミングするにあたりアクセストークン自体の管理を意識する必要はありません。

 

Lambda関数では、Alexaサービスからのリクエストに含まれるアクセストークンを参照し、Webサービスへのアクセスに利用します。Alexa SDKのインテントハンドラではアクセストークンはthis.event.session.user.accessTokenメンバーで参照できますが、アカウントリンクが未設定の場合、メンバーが未定義になるため、値のチェック処理を必ず含めるようにプログラミングしましょう。また、未設定の場合は後述のホームカードからアカウントリンク設定を促すレスポンスを返すことができます。こちらも利用しましょう。

var accessToken = this.event.session.user.accessToken;
if (accessToken === undefined) {
  // アクセストークンが未定義の場合はアカウントリンク設定を促す
  var message = 'スキルを利用するためにログインを許可してください';
  this.emit(':tellWithLinkAccountCard', message);
  return;
}

Webサービスへのアクセスは、一般的なライブラリのほか、Webサービス用のSDKがあればそれらを利用するのもよいでしょう。Lambda関数で追加のライブラリやSDKを利用する場合は、Lambdaパッケージにそれらを含めてアップロードする必要があることに注意してください。Lambdaパッケージの取り扱いの詳細については、AWS Lambdaドキュメントを参照してください。

• デプロイパッケージの作成 (Node.js) - AWS Lambda

 

アカウントリンクでは、OAuth 2.0の承諾タイプのうち以下の2つをサポートします。連携するWebサービスがサポートするタイプを選択しましょう。

• Authorization Code Grant (開発者コンソールではAuth Code Grant)
• Implicit Grant

 

承諾タイプごとのアカウントリンクのフローを示します。

Authorization Code Grantのフロー

 

Implicit Grantのフロー

 

連携するWebサービスが満たすべき要件などの詳細は、ドキュメントを参照してください。

• Alexaユーザーとシステムユーザーを関連付ける

 

また、リンクアカウントは複数のシステムが連携する仕組みで、設定や検証にはいくつか気をつけるべきポイントがあります。それらをまとめた以下のブログ記事（英語）も参考になるでしょう。

• 10 Tips for Successfully Adding Account Linking to Your Alexa Skill : Alexa Blogs

 

5-2. (参考) ホームカードの利用

Alexaアプリには、Alexaサービスからのレスポンスに含まれる情報を表示するホームカードという機能があります。ホームカードを利用することで、音声での情報に加えて視覚的な情報をユーザーに提供することができます。ホームカードは3種類あり、Alexaサービスへのレスポンスに指定します。Alexa SDKでは、レスポンス生成時のアクションでホームカードを含むものを選択します。

 

• Simple : タイトルとテキストデータのみを指定するシンプルなカード
• Standard : Simpleに加え、画像を表示できるカード
• LinkAccount : リンクアカウント設定を促すカード

 

プログラミング例を示します。

var message = '今日の天気は晴れです';
var cardTitle = '今日の天気';
var cardMessage = '晴れ 最高20℃ 最低16℃';
this.emit(':tellWithCard', message, cardTitle, cardMessage); // tellWithCardアクションでSimpleカードを表示

設定方法の詳細は、ドキュメントやAlexa SDKのREADMEを参照してください。

• スキルの応答にカードを追加する | カスタムスキル
• alexa/alexa-skills-kit-sdk-for-nodejs: The Alexa Skills Kit SDK for Node.js helps you get a skill up and running quickly, letting you focus on skill logic instead of boilerplate code.

 

今回の実習

OAuth 2に対応するWebサービスとしてLogin with Amazonと連携し、Amazonアカウントの氏名を取得するスキルを作成します。

 

ユーザー : 「アレクサ、リンクテストで名前を教えて」

Alexa : 「山田太郎(Amazonアカウントに登録している氏名)さん、こんにちは。」

 

1. Login with Amazonの設定
2. スキルの作成と構成
3. AWS Lambda関数の構成
4. Alexaアプリのアカウントリンク設定
5. 動作確認

 

ステップ1 Login with Amazonの設定

Login with Amazonは、Amazonアカウントと他のWebサービスをOAuth 2で連携するサービスです。Login with Amazonは、Alexaスキルと同様にAmazon開発者コンソールで設定できるセキュリティプロファイルを利用します。

 

1. Webブラウザで https://developer.amazon.com/ja/ にアクセス、サインインします

2. 開発者コンソールのメニューから[アプリ&サービス] - [Amazonでログイン]を選択します

3. [Create a New Security Profile]ボタンをクリックします
 

4. セキュリティプロファイル作成画面では、以下を入力します

• Security Profile Nameは「Alexa Account Linking Test」と入力
• Security Profile Descriptionは「Alexa Account Linking Test profile」と入力
• Consent Privacy Notice URLは「http://example.com/privacy.html」と入力
  (動作確認を目的とし、今回はダミーURLを利用する)
• [Save]ボタンをクリックします

5. 作成されたセキュリティプロファイルの [Show Client ID and Client Secret] リンクをクリックし、表示される「Client ID」と「Client Secret」をコピーしておきます。このあとのステップ3のアカウントリンク設定で利用します。

6. 開発者コンソール画面を開いたまま、次のステップに進みます。

 

ステップ2 AWS Lambda関数の構成

今回の実習で使用するLambda関数を作成します。関数では、Amazonアカウントの氏名をレスポンスとして返すシンプルな処理をプログラミングします。

 

1. AWSマネジメントコンソールにログインし、画面左上の[サービス]をクリックします。テキストボックスに「lambda」と入力して候補に表示されるLambdaを選択します。AWS Lambdaの管理画面が表示されます。
2. AWS Lambdaの初期画面が表示されたら、「関数の作成」ボタンをクリックします。
3.  [設計図の選択] 画面では検索フォームに「alexa」と入力し、リストされる「alexa-skill-kit-sdk-factskill」をクリックします。
4. [基本的な情報] 画面では、[名前]に「AccountLinkingTestSkill」、[ロール]は「既存のロールを選択」のまま、[既存のロール]は第1回の実習で作成した「lambda_basic_execution」を選択します。次に[関数の作成]ボタンをクリックしLambda 関数を作成します。
5. 作成されたAccountLinkingTestSkill関数の設定画面に遷移したら、[関数コード] のコード編集テキストエリアに以下のソースコードを貼り付けます。

   "use strict";
   const Alexa = require('alexa-sdk');
   const https = require ('https');
   
   exports.handler = function(event, context, callback) {
     var alexa = Alexa.handler(event, context);
   
     //alexa.appId = process.env.APP_ID;
     alexa.registerHandlers(handlers);
     alexa.execute();
   };
   
   var handlers = {
     'LaunchRequest': function () {
       this.emit('AccountLinkingTestIntent');
     },
     'AccountLinkingTestIntent': function () {
         var self = this;
       // アクセストークンの取得
       var accessToken = this.event.session.user.accessToken;
       if (accessToken === undefined) {
         // トークン未定義の場合はユーザーに許可を促す
         this.emit(':tellWithLinkAccountCard','スキルを利用するためにAmazonでのログインを許可してください');
         return;
       }
       // Login with AmazonのリクエストURLにアクセストークンを付与
       var url = 'https://api.amazon.com/user/profile?access_token=' + accessToken;
       // httpsモジュールでリクエストを送出
       https.get(url, function(res) {
         // レスポンスを格納する空の変数を定義
         var body = '';
         res.setEncoding('utf8');
         res.on('data', function(chunk) {
           // レスポンスボディーを変数に追加
           body += chunk;
         });
         res.on('end', function (res) {
           // レスポンスボディーはJSON形式なので、そこから氏名を取り出す
           var name = JSON.parse(body).name;
           self.emit(':ask', name + 'さん、こんにちは');
         });
       }).on('error', function(e) {
         self.emit(':tell', "通信に問題が発生しました");
       });
       }
   };

    

6.  [トリガー]タブの[+トリガーを追加]をクリックし、ダイアログ左側の点線枠をクリックして「Alexa Skills Kit」を選択し「送信」ボタンをクリックします。
7. 画面右上の[保存してテスト]ボタンをクリックします。
8. テストイベントが未作成の場合、テストイベント作成のダイアログが開きます。[イベントテンプレート]から「Alexa Start Session」を選択し [イベント名] に「MyAlexaEvent」と入力し[作成]ボタンをクリックします。
9. 再度画面右上の[テスト]ボタンをクリックしてAccountLinkingTestSkill関数の実行をテストします。
10. 「実行結果: 成功」と表示されたら、[詳細]をクリックし結果を確認します(アカウントリンクを促すレスポンスが表示さレます)。
11. 画面右上の「ARN」に表示されるARN(Amazonリソースネーム)をコピーしておきます。

 

ステップ3 スキルの作成と構成

前回までの実習と同様に動作テストするためのAlexaスキルを新規作成し、アカウントリンクを有効にします。

 

1. Webブラウザの別のタブやウィンドウを開き、 https://developer.amazon.com/ja/ にアクセスし、サインインします。

2. 開発者コンソールの「ALEXA」タブをクリックします。

3. Alexa Skills Kitの「始める >」をクリックします。

4. 画面右上の「新しいスキルを追加する」をクリックします。

5. [スキル情報]画面で以下のようにカスタムスキルを設定します。

• [スキルの種類]は「カスタム対話モデル」が選択されていることを確認
• [言語]は「Japanese」(日本語)を選択
• [スキル名]は「リンクテスト」と入力
• [呼び出し名]は「リンクテスト」と入力
• [グローバルフィールド]は既定のままにし、[保存]をクリック
• 画面右下に出てくる[次へ]をクリック

6. [対話モデル]画面では、以下のように設定します。

• [インテントスキーマ]には、以下のJSONをコピー&ペーストで入力する。

{
  "intents": [
    {
      "intent": "AccountLinkingTestIntent"
},
    {
      "intent": "AMAZON.HelpIntent"
},
{
      "intent": "AMAZON.StopIntent"
},
{
      "intent": "AMAZON.CancelIntent"
    }
  ]
}

•  [サンプル発話]には、以下のテキストデータをコピー&ペーストで入力する

AccountLinkingTestIntent 私 の 名前 は
AccountLinkingTestIntent 私 の 名前 を 教えて
AccountLinkingTestIntent 私 の 名前 を 教えて くれる
AccountLinkingTestIntent 私 の 名前 を 教えて くれる かな
AccountLinkingTestIntent 名前 は
AccountLinkingTestIntent 名前 を 教えて
AccountLinkingTestIntent 名前 を 教えて くれる
AccountLinkingTestIntent 名前 を 教えて くれる かな

• [次へ]をクリック

7. [設定]画面に遷移したら、[サービスエンドポイントのタイプ]から「AWS Lambda の ARN (Amazonリソースネーム)」のラジオボタンをクリック、[デフォルト]にステップ2で作成したLambda関数のARNをペーストする

8. アカウントリンクの「ユーザーにアカウントの作成や既存のアカウントへのリンクを許可しますか？」のチェックボックスをオンにし、以下を入力します。

• [認証 URL]は「https://www.amazon.com/ap/oa」(全ユーザー共通)
• [クライアント ID]はステップ1の「Client ID」をペースト
• [スコープ]は、[スコープを追加 +]リンクをクリックして「profile」(Login with Amazonではアカウントのプロフィールを指す)を入力
• [リダイレクトURL]は、表示される全てのURLをコピーしておく
• [認可の承諾タイプ]は「Auth Code Grant」を選択
• [アクセストークンURL]は「https://api.amazon.com/auth/o2/token」(全ユーザー共通)
• [クライアントシークレット]は、ステップ1の「Client Secret」をペースト
• [次へ]をクリックして設定する
  
• スキルのテスト画面に遷移したらWebページを表示したままにしておく

9. ステップ1で設定した開発者コンソールのLogin with Amazonの画面を表示します。

10.セキュリティプロファイル一覧から、作成したセキュリティプロファイルの右側にある歯車アイコンをクリックし、[Web Settings] を選択します。

11. 画面右下の[Edit]ボタンをクリックします。

12. [Allowed Return URLs]に手順8でコピーしたリダイレクトURLをペーストします。2つ目以降は[Add Another]リンクをクリックしてテキストボックスを追加してペーストします。

13. [Save]ボタンをクリックします。

 

ステップ5 動作確認

サービスシミュレーターでスキルの動作を確認しましょう。アカウントリンクによりLambdaがAmazonアカウントの氏名を取得します。スキルのレスポンスの中に Amazon アカウントの氏名の情報が含まれていることを確認します。

 

1. Alexaアプリを開きメニューから[スキル]を選択、右上の[有効なスキル]をクリックもしくはタップします。
   
2. スキル一覧から今回作成した「リンクテスト」スキルに「アカウントのリンクが必要です」という警告が表示されていることを確認し、選択します。
3. [設定]ボタンをクリックもしくはタップします。
4. [アカウントをリンク]のリンクをクリック、もしくはタップします(Webブラウザがポップアップを抑止する場合は、その設定を解除してください)。
5. Amazonのログイン画面が表示されるたら、アカウント情報を入力して[ログイン]ボタンをクリックします。
   
6. Login with Amazonから作成したスキルへのアクセス許可画面が表示されます。許可内容(Amazonアカウントのプロフィールへのアクセス)を確認し、[許可]ボタンをクリックします。
   
7. リンク完了の画面が表示されたら、タブもしくはウィンドウを閉じます。
   
8. Alexaアプリのスキル設定画面に「リンク済み連結」と表示されることを確認します。
9. Amazon開発者コンソールを開き、リンクテストスキルを選択し、[テスト]タブを表示します。
10. サービスシミュレーターの[発話を入力してください]に「名前を教えて」と入力し [リンクテストを呼び出す]ボタンをクリックします。[サービスレスポンス]に表示される文字列の中に自分の名前が含まれていることを確認します。
    

 

これで今回の実習は完了です。スキルからAmazonのアカウント情報を取得する様子を確認できました。

 

まとめ

第5回ではアカウントリンク機能について学習しました。次回はスキルの公開申請とテスト、SSMLについてご紹介します。

Source: Alexa Developer Blog