デジタルサイネージ編の第4回です。
前回の記事ではPowerPointの準備までを説明しました。
今回はGroupSessionのWEB APIについて説明します。
WEB API仕様の入手
これまでの説明通りに進めてこられた方はGroupSessionのWEB APIが有効になっているかと思います。
WEB APIの利用、といくまえにWEB APIの仕様を確認しておきます。
仕様を確認するために本サイトから仕様書をダウンロードします。「WEB API仕様書」と書かれているものです。常に最新版が掲載されているので、旧版と取り間違えることはないでしょう。(逆に言うと、旧版は入手できません)
ダウンロードが終わったら早速開いてみましょう。
WEB API仕様を読む
私が始めてこの仕様書を見て感じたのは「なんとざっくばらんな…」という印象でした。必要なことしか書いていない、と言えば聞こえはいいのですが、読み手側の都合など関係無しという感が否めません。
個人的な感想はさておき、必要な情報をピックアップしていきます。
- 認証について
- レスポンス(応答)
- パラメータ送信方法
- 利用する機能
- ユーザの個人情報を検索
- スケジュール検索
2ページ目に記載がありますが、BASIC認証となります。つまりアクセスに行ったときにユーザ名とパスワードを問われる形式です。一度認証が通ると、セッションが有効な期間は再度聞かれることはありません。公開スケジュールにアクセスできるユーザの情報があればOKです。(本連載では「ほげ」です)
WEB APIではサーバーへ問い合わせた際、何らかの結果がXMLで返ってきます。正常時であれば<Result></Result>のようなタグで囲まれたデータ群が、不正時であれば<Errors></Errors>タグで囲まれたデータが返ってきます。
GET/POSTどちらも使用可能です。GET指定の場合、リクエストURLに連結して送りますので
http://(サーバー名)/gsession/api/schedule/search.do?usid=(ユーザSID)&startFrom=2014/06/05
のような指定になります。POST指定の場合はリクエストURL
http://(サーバー名)/gsession/api/schedule/search.do?
にプラスして送信フォームデータに「usid (ユーザSID)」「startFrom 2014/06」を付けて送ります。
URL(/api/user/search.do?)
スケジュールを検索するに当り、各ユーザのUSIDが必要になります。リクエスト時にパラメータなしで送ると登録されているユーザの情報が一括で引き出せます。デフォルトでは50名分なので、ユーザ登録数が50を超えるときはresultsパラメータを変更します。ただし、最大数は100です。
URL(/api/schedule/search.do?)
各ユーザの公開スケジュールを取得します。リクエスト時にユーザSIDを省略することは可能ですが、その際、レスポンスは自分自身のスケジュールとなります。つまり、全員のスケジュールを把握するには登録ユーザ回数問い合わせる必要があります。
ユーザの個人情報を検索
URL(/api/user/search.do?)
タイトル通りですが、ユーザの個人情報を検索します。実際に欲しいデータはレスポンスフィールドにある<Usid></Usid>のみです。
レスポンスのフォーマットは
<ResultSets Count="1" TotalCount="1" Page="1" MaxPage="1" url="/gsession/api/user/search.do">
<Result>
<Usrsid> </Usrsid>
～
<GroupSet> </GroupSet>
</Result>
</ResultSets>
となります。複数件あるときはCount、TotalCount、Pageなどが変わります。
<ResultSets Count="40" TotalCount="40" Page="1" MaxPage="1" url="/gsession/api/user/search.do">
<Result>
<Usrsid> </Usrsid>
～
<GroupSet> </GroupSet>
</Result>
～
<Result>
<Usrsid> </Usrsid>
～
<GroupSet> </GroupSet>
</Result>
</ResultSets>
リクエストパラメータで使えそうなのは取得件数を指定する「results」くらいでしょうか。表示させたいスケジュールは時系列で指定・取得するため、ユーザの役職や従業員番号などに依存しません。つまり、ここでソート(並び替え)を指定する意味もありません。
単純にユーザ検索として見たとき、役職検索、年齢検索、出身地検索(登録していれば)など、他の案件では利用できるかもしれません。
スケジュール検索
URL(/api/schedule/search.do?)
スケジュール検索を行います。ここではユーザSIDとstartFrom、startTo、endFrom、endToを指定します。日付は確実に当日のみを指定するため、全て指示します。
一度startFrom、startTo、endFrom、endToについて整理します。
GroupSessionのスケジュールとstartFrom、startTo、endFrom、endToは以下の関係となっています。
よって当日開催、当日終了のスケジュールを指定するには
のように、startFrom、startTo、endFrom、endTo全てが同じ内容になります。
少し厄介なのが複数日に渡って開催される会議です。
startFromは起算日より前のため過去を指定、startToは当日、endFromも当日、endToは当日、もしくは未来となります。
今回は簡易的に当日で完結するスケジュール(会議)しかないと仮定して進めます。
ここで注意したいのが、WEB APIで指定する日付フォーマットです。仕様書に日付指定は「yyyy/MM/dd hh:mm」と書かれていますが、このフォーマットで送信するとエラーとなります。正しくは「yyyy/MM/dd」です。この記載ミスはWEB API実装当初から残っていますね。
該当スケジュールがあった際にはレスポンス(フォーマット)が返ってきます。
<ResultSet TotalCount="1" Start="1" url="/gsession/api/schedule/search.do">
<Result>
<Schsid>12345</Schsid>
<SchKf>0</SchKf>
<Title>XYZ株式会社ご来社</Title>
<Naiyo><DS><BR><CMP>XYZ株式会社</CMP><BR><CST>第一開発部 高橋部長</CST><BR><CHG>橋本課長</CHG><BR></DS><BR><BR>進捗確認について<BR></Naiyo>
<Biko/>
<StartDateTime>2014/06/04 09:00:00</StartDateTime>
<EndDateTime>2014/06/04 12:00:00</EndDateTime>
<TimeKbn>0</TimeKbn>
<UserKbn>0</UserKbn>
<UserSid> </UserSid>
<UserName>ほ げ</UserName>
<ColorKbn>1</ColorKbn>
<AbleEdit>1</AbleEdit>
<AddUserName>ほ げ</AddUserName>
<ADateTime>2014/06/04 11:23:18</ADateTime>
<EDateTime>2014/06/04 11:23:18</EDateTime>
<CompanySet Count="0"/>
</Result>
</ResultSet>
スケジュールの備考は「
事例に挙げているレスポンスフィールドは以前登録したスケジュールのものですが、内容欄に入力したタグ情報が
<タグ名>～</タグ名>
ではなく
<タグ名>～</タグ名>
に変換されています。XML内に'<‘や’>’が表記できないためのエスケープだと思いますが、スケジュールから会社名や顧客名、担当名を抽出する際には注意が必要です。
GETがいい?POSTがいい?
今回使用するWEB APIにバイナリデータを扱うものはありません。ファイル管理などデータをアップロードする場面ではPOST指定でなければ実現できませんが本件は取り扱いません。GETでもPOSTでもレスポンスは同じですから使いやすい方を選択すればいいでしょう。
次回ではいよいよ、PowerPointでVBAを組んでいきます。
