予約・利用データを BI ツールに取り込む
予約、ルームの利用状況、在室データを Power BI や Tableau などの BI ツールへ取り込む方法 — 利用回数・利用分数・利用率を返す分析用の呼び出し、同じ予約をスプレッドシートとして返す呼び出し、レポート用クライアントに必要な読み取りスコープ、そしてそれぞれのページング・期間・行数の上限。ファイルを 1 つダウンロードするだけでよい場合の Excel と CSV のボタンの場所も。
予約データと利用データが Offision から出ていく道は 2 つあります。レポート画面から誰かがダウンロードするファイルか、REST API です。API は同じ予約を行単位で返し、利用状況は集計済みの数値で返します。Power BI、Tableau をはじめどのレポートツールも、このどちらかを使います。
ファイルで取るか、API を呼ぶか
今日中に数字が必要なら、ファイルで取ります。一覧とレポートの各画面は Excel または CSV で自身をエクスポートできます。エクスポートボタンの場所に一覧があり、どのレポートがどの疑問に答えるかが各レポートの中身を説明しています。そのまま分析に回すことを前提に作られているダウンロードは、予約分析のピボットテーブル ユーザーリソース利用レポートで、ブックには Raw data シート — 組み合わせごとに 1 行のフラットな形、ピボットテーブルが期待する形 — が含まれます。
API を呼ぶのは、誰もいない時間に繰り返し取得したいとき、画面に収まらない長い期間をまたぐとき、スプレッドシート以外の場所に取り込むときです。
呼び出しに必要なもの
マーケットプレイス の API 認証 で作成する連携クライアントです。長期有効な アクセストークン か、シークレットを 1 日有効な Bearer トークンに交換する OAuth2 クライアント のどちらかになります。どちらの仕組みも、その周りの守りも 自社システムをつなぐ にあります。
API 認証を開くレポート用クライアントは読み取りしかしないので、all.read ではなく
booking.read、analyze.read、bookableResource.read、building.read、
user.read、userGroup.read、dashboard.read を与えます。トークンはクライアントに許された範囲より狭く要求できても、広くはできません。
レポートが使う呼び出し
| 欲しいもの | 呼び出し | 返ってくるもの |
|---|---|---|
| すべての予約を行として | リソース予定 | 予約 1 件につき 1 行、ページング付き。日付、リソース、リソース種別、主催者、予約ステータス、フリーテキストで絞り込み |
| 同じ予約をスプレッドシートで | 予約エクスポート | 指定したタイムゾーンでの .xlsx ストリーム。メールドメインを 1 つ指定することも可 |
| ルームごとの利用量 | リソース別の予約 | リソースごとの予約件数、利用分数、利用率 |
| その推移 | 時間別の予約 | 同じ 3 つの数値を期間ごとに — 5 分単位から月単位まで |
| 予約ではなくセンサーが捉えた在室 | リソース別の在室、および時間別の対になる呼び出し | 同じ 2 つの形を、予約ではなく実測で |
| 1 日の来訪者数 | 来訪者バッジ統計 | その日の予定、滞在中、退出済み、未到着、滞在超過の件数 |
| ID の背後にある名前 | リソース と 建物、ユーザー とそのグループ | 数値を結合する相手。部署を返す呼び出しはなく、ユーザーグループが最も近いもの |
3 つの呼び出しが返すものを並べたところ。予約 1 件につき 1 行か、ルーム別・期間別に集計済みの行か。
期間、ページング、上限
- 分析の呼び出しには必ず
fromとtoを送ります。 省略すると両方が現在時刻になり、すべてではなく空の期間が返ります。 - 予約の行はページングされます。 指定しなければ 1 ページ 30 件で、どこまで辿ればよいか分かるよう総件数がデータに添えられます。
- リソース別の利用はページングされず、9,999 行で止まります。それを超える規模では、フロア単位で取得してください。
- スプレッドシートの呼び出しは 1 回 2 か月まで。 JSON の呼び出しにこの制限はないので、1 年分の抽出はエクスポートではなく行のループになります。
- 5 秒あたり 1,000 リクエスト、トークンごと。超えると 429 と、待つべき時間を示す
Retry-Afterが返ります。
各ルートがどこまで遡れるか。JSON の呼び出しに期間の上限はなく、利用レポートのダウンロードは 1 年、スプレッドシートの呼び出しは 2 か月で止まります。
抽出を新しく保つ
多くのレポートはスケジュールで動きます — 毎晩、移動する期間を読み直し、重複除去は取り込み先に任せます。それより早く知りたい場合、
bookableResource.readwrite を持つクライアントは、指定したリソースに対してコールバック URL を登録でき、そのリソースの予約が変わると Offision が POST します。
できないこと
- データベースには接続できません。 ODBC や JDBC のドライバーはなく、データへの直接接続もありません。すべて上記のエクスポートか API を通します。
- インストールするコネクターはありません。 Power BI、Tableau、Zapier、 Power Automate はいずれも、ふつうの REST クライアントとして Offision を呼ぶか、エクスポートしたファイルを読みます。
- 抽出データを送り出す仕組みはありません。 最も近いのは予約サマリーのメール で、スケジュールに従ってスプレッドシートを添付します。
- 監査証跡は API にありません。 専用の画面からダウンロードするだけです — 監査証跡 を参照してください。
- 大きすぎるエクスポートは切り詰められず拒否され、期間やフィルターを絞るよう促されます。そのとおりにするか、API に切り替えてください。