Alexa for Business API を使用してみました #reinvent #Alexa

2017.12.09

1 はじめに

先日のブログで紹介したとおり、Alexa for Businessでは、従来のAlexa Skill Kit(ASK)にAlexa for Business APIを組み合わせることで、オフィスを快適にするための色々なスキルを作成できるようになっています。

今回は、2017年12月6日に公開された、このAPIで実際にどのような事ができるのか、少し試してみました。

2 リファレンスの列挙

下記は、Alexa for Business APIsの全てです。一度、AWSコンソールでAlexa for Businessを触ったことがある方には、恐らくファンクション名だけで、何ができるのか、概ね想像できるのではないでしょうか。

Fanction Detail
AssociateDeviceWithRoom 部屋にデバイスを関連付ける
AssociateSkillGroupWithRoom 部屋にスキルグループを関連付ける
CreateProfile 部屋のプロファイルの作成
CreateRoom 部屋の作成
CreateSkillGroup スキルグループの作成
CreateUser ユーザーの作成
DeleteProfile 部屋のプロファイルの削除
DeleteRoom 部屋の削除
DeleteRoomSkillParameter 部屋のスキルパラメータの削除
DeleteSkillGroup スキルグループの削除
DeleteUser ユーザーの削除
DisassociateDeviceFromRoom 部屋へのデバイスの割当
DisassociateSkillGroupFromRoom スキルグループの部屋への割当
GetDevice デバイスの取得
GetProfile 部屋のプロファイルの取得
GetRoom 部屋の取得
GetRoomSkillParameter スキル・パラメータの取得
GetSkillGroup スキルグループの取得
ListSkills スキルの列挙
ListTags タグの列挙
PutRoomSkillParameter スキル・パラメータの設定
ResolveRoom スキルID及びユーザIDから部屋の情報を取得する
RevokeInvitation 招待状を無効化する
SearchDevices デバイスの検索
SearchProfiles 部屋のプロファイルの検索
SearchRooms 部屋の検索
SearchSkillGroups スキルグループの検索
SearchUsers ユーザーの検索
SendInvitation 招待状の送信
StartDeviceSync デバイス動機の開始
TagResource リソースへのタグの設定
UntagResource リソースからタグを削除
UpdateDevice デバイス情報の更新
UpdateProfile 部屋のプロファイルの更新
UpdateRoom 部屋情報の更新
UpdateSkillGroup スキルグループ情報の更新

3 実際に使ってみる

それでは、実際に少し触ってみることにします。

リファレンスを見ると分かるのですが、殆どのAPIは、リソースのARNを指定して利用します。しかし、Alexa for BusinessのAWSコンソールでは、ARNが表示されていません。そこで、それを取得することから始めます。

APIの中で、Searchで始まるものは、そのためのAPIであり、リソースを列挙することで、ARNが判明します。

(1) searchDevices

下記は、searchDevicesを試している様子です。

var AWS = require('aws-sdk');
AWS.config.update({region: 'us-east-1'});
var alexaforbusiness = new AWS.AlexaForBusiness();

var params = {
    Filters: [
      {
        Key: 'DeviceType',
        Values: ['Dot']
      },
    ],
    MaxResults: 10,
    SortCriteria: [
      {
        Key: 'DeviceType',
        Value: "ASC"
      },
    ]
};

alexaforbusiness.searchDevices(params, function(err, data) {
    if (err) {
        console.log(err, err.stack);
    } else {
        console.log(data);
    }    
});

現在、2台のデバイスを登録しているので、実行結果は、以下のとおりとなりました。(シリアル番号等は、編集しています)

$ node index.js
{ Devices:
   [ { DeviceArn: 'arn:aws:a4b:us-east-1:xxxxxxxxxxxx:device/139be5a7f71582a126b011df1cecc9ec/XXXXXXXXXXXXXXXX:A3S5BH2HU6VAYF',
       DeviceSerialNumber: 'XXXXXXXXXXXXXXXX',
       DeviceType: 'Dot',
       SoftwareVersion: '595459620',
       MacAddress: 'XX:XX:XX:XX:XX:8E',
       DeviceStatus: 'READY',
       RoomArn: 'arn:aws:a4b:us-east-1:xxxxxxxxxxxx:room/139be5a7f71582a126b011df1cecc9ec/dcb01211b6xxxxxxxxxd1c5631db2c7',
       RoomName: 'Room002' },
     { DeviceArn: 'arn:aws:a4b:us-east-1:xxxxxxxxxxxx:device/139be5a7f71582a126b011df1cecc9ec/XXXXXXXXXXXXXXXX:A3S5BH2HU6VAYF',
       DeviceSerialNumber: 'XXXXXXXXXXXXXXXX',
       DeviceType: 'Dot',
       SoftwareVersion: '595459620',
       MacAddress: 'XX:XX:XX:XX:XX:C8',
       DeviceStatus: 'READY',
       RoomArn: 'arn:aws:a4b:us-east-1:xxxxxxxxxxxx:room/139be5a7f71582a126b011df1cecc9ec/30b0120bxxxxxxxxxxxb1546619124',
       RoomName: 'Room001' } ],
  TotalCount: 2 }

この結果から、デバイスと、それに紐付いている部屋のARNが取得できています。

パラメータ等の詳細は、下記をご参照下さい。
http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/AlexaForBusiness.html#searchDevices-property

(2) getRoom

もう一つ、上記で取得できた、部屋のARNを利用して

var params = {
    RoomArn: 'arn:aws:a4b:us-east-1:XXXXXXXXXXXX:room/139be5a7f71582a126b011df1cecc9ec/dcb01xxxxxxxxxxxxxxxx631db2c7'
};
alexaforbusiness.getRoom(params, function(err, data) {
    if (err) {
        console.log(err, err.stack);
    } else {
        console.log(data);
    }
});

今度は、部屋のプロファイルも取得できています。

$ node index.js
{ Room:
   { RoomArn: 'arn:aws:a4b:us-east-1:XXXXXXXXXXXX:room/139be5a7f71582a126b011df1cecc9ec/dcb01211b6xxxxxxxxxxxxxxx31db2c7',
     RoomName: 'Room002',
     ProfileArn: 'arn:aws:a4b:us-east-1:XXXXXXXXXXXX:profile/139be5a7f71582a126b011df1cecc9ec/42b0120xxxxxxxxxxxxxxxf12f4' } }

パラメータ等の詳細は、下記をご参照下さい。
http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/AlexaForBusiness.html#getRoom-property

3 ResolveRoom

提供されているAPIは、AWSコンソールからの操作と同じです。しかし、ResolveRoomだけは、ちょっと特異です。

このAPIは、スキルIDとUserIdを使用していますが、この2つの情報はスキル自身が取得可能な値です。

そして、取得できるデータは、下記のとおりです。

このAPIを使用すると、実行中のスキルは、その呼び出し元を特定し、Alexa for Business上のリソース情報と紐つける事ができるわけです。

デモ・ビデオでコピー紙の補給を注文していたスキルは、きっとこのAPIを使用しているのでしょう。

4 最後に

今回は、Alexa for BusinessのAPIを試してみました。リソースのARNさえ取得できれば、使用方法は、それほど複雑ではないようです。

また、ResolveRoomで、実装中のスキルから、Alexa for Business上のデバイスとのヒモ付も可能です。

今後、これらの機能を駆使して、エンタープライズ向けのスキルに挑戦してみたいと思います。

5 参考リンク


Alexa for Business API Reference
Alexa for Business デバイスのセットアップ編 #reinvent #Alexa
Alexa for Business 部屋の管理編 #reinvent #Alexa
Alexa for Business プライベートスキルを作ってみました #reinvent #Alexa
Alexa for Business スキル管理編 #reinvent #Alexa
Alexa for Business プライベートスキルでアカウントリンクをやってみました #reinvent #Alexa
Alexa for Business 用のエンタープライズ向けスキル #reinvent #Alexa