把預約與使用資料帶進 BI 工具
把預約、會議室使用率和在室資料帶進 Power BI、Tableau 或任何其他 BI 工具：哪些分析呼叫會回傳使用次數、分鐘數和百分比，哪一個把同一批預約以試算表串流回來，報表用戶端需要哪些唯讀權限範圍，以及各自的分頁、期間與列數上限——還有當你只需要下載一份檔案時，Excel 和 CSV 按鈕在哪裡。
預約和使用資料離開 Offision 有兩條路：由某個人從報表畫面下載的檔案，或是 REST API——它把同一批預約以列的形式回傳，使用率則已經先算好。Power BI、Tableau 和其他每一種報表工具，都是走這兩條路的其中一條。
拿檔案，還是呼叫 API
如果今天下午就要一個數字，那就拿檔案。每個清單和報表畫面都能把自己匯出成 Excel 或 CSV；匯出按鈕都在哪裡列了全部，而哪份報告回答哪個問題說明每份報表裝了什麼。專為後續分析而做的下載是預約分析的樞紐分析表使用者資源使用報告，它的活頁簿帶有 Raw data 工作表——每個組合一列的扁平格式，也就是樞紐分析表期待的形狀。
當這份擷取必須在沒有人在場的情況下重複執行、要跨越比畫面能顯示更長的期間，或者要落在試算表以外的地方時，就呼叫 API。
一次呼叫需要什麼
一個整合用戶端，在 市集 底下的 API認證設定 建立，可以是長效的 Access token，也可以是拿密鑰換取每日 Bearer 權杖的 OAuth2 用戶端。連接你自己的系統 說明了兩者的運作方式和周邊的防線。
開啟API認證設定報表用戶端只會讀取，所以給它 booking.read、analyze.read、
bookableResource.read、building.read、user.read、userGroup.read 和
dashboard.read，而不是 all.read——權杖可以要求比用戶端持有的更少，但永遠不能更多。
一份報表會用到的呼叫
| 你想要什麼 | 呼叫 | 回傳什麼 |
|---|---|---|
| 每一筆預約，以列呈現 | 資源預約 | 每筆預約一列，分頁。可依日期、資源、資源類型、召集人、預約狀態或自由文字縮小範圍 |
| 同一批預約，以試算表呈現 | 預約匯出 | 一個 .xlsx 串流，使用你指定的時區，也可只取一個電子郵件網域 |
| 每間會議室被用了多少 | 依資源的預約 | 每個資源的預約次數、使用分鐘數、使用百分比 |
| 這個數字怎麼隨時間變化 | 依時間的預約 | 同樣三個數字，依時段切分——五分鐘到每月 |
| 感應器看到的，而不是被預約的 | 依資源的在室，以及依時間的另一支 | 同樣兩種形狀，但是實測而非預約 |
| 某一天的訪客人數 | 訪客證統計 | 那一天的預計、在場、已離開、未到和逾時停留數 |
| ID 背後的名稱 | 資源和大樓、使用者及其群組 | 你拿來和數字做關聯的對象。沒有部門這支呼叫——使用者群組是最接近的 |
三個呼叫回傳的東西並排比較：每筆預約一列，或是已依會議室、依時段算好的列。
期間、分頁與上限
- 呼叫分析一定要送
from和to。 省略的話兩者都會變成當下這一刻，回傳的是一個空白期間，而不是全部。 - 預約的列會分頁，未指定時一頁三十筆，資料旁邊附上總數，讓你知道還要走多遠。
- 依資源的使用率不分頁，到 9,999 列就停。規模超過這個數字時，改成一層樓一層樓取。
- 試算表那支呼叫一次只收兩個月。 JSON 的呼叫沒有這個限制，所以跨一整年的擷取是在列上迴圈，而不是在匯出上。
- 每五秒一千次請求，以權杖計。超過就回 429，並在
Retry-After告訴你要等多久。
每條路徑能回溯多久：JSON 呼叫沒有期間上限，使用報告下載到一年為止，試算表呼叫到兩個月為止。
讓擷取保持新鮮
多數報表是排程跑的——每晚重讀一段會移動的期間，重複的資料交給資料倉儲處理。想要更即時，持有 bookableResource.readwrite 的用戶端可以針對指定的資源註冊一個回呼網址，當其中一個資源上的預約有變動時，Offision 就會 POST 過去。