連接 Google Calendar

本指南說明如何將 Google Calendar 連接到工作區。這項連接以工作區為單位：它會把該工作區的活動以唯讀方式同步到 Control Center。完整說明請參閱日曆與排程。

連接帳戶

在側邊欄開啟日曆。
在日曆側邊欄中點擊新增日曆帳號。（同一區段也位於設定 → 工作區 → 個人資料與身分的 Google Calendar 之下。）
選擇授權方式：
- 使用 Control Center 的 Google 應用程式 — 無需任何設定。當你的組建附帶此應用程式時，這就是預設選項。
- 使用我自己的 Google Cloud 用戶端 — 貼上你自己專案的用戶端 ID 和密鑰（請參閱自備 Google 用戶端）。
點擊連接 Google Calendar。對話框會顯示一組簡短代碼，以及 Google 裝置頁面的連結。
在任何裝置上開啟該頁面，輸入代碼並核准所要求的存取權。對話框會自行關閉，你的活動隨即開始同步。

執行這段交換、並保存所產生重新整理權杖的是伺服器，而不是你的裝置——這正是代碼要在「任何裝置」上核准，而非必須在本應用程式中的原因。

帳戶只會連接到目前作用中的工作區。切換工作區後，你看到的會是該工作區的日曆。

連接流程會要求 calendar.readonly 加上你的電郵——內建應用程式和你貼上的用戶端所要求的範圍相同。Control Center 會讀取活動，不會在 Google 上建立、編輯、刪除或回覆邀請。

同步的運作方式

排程由伺服器掌管：它每兩分鐘掃描每個工作區已連接的帳戶，並把活動寫入該工作區的資料庫。用戶端從不直接與 Google 通訊——它們只讀取伺服器寫入的內容。

掃描是增量式的。每個日曆的第一次掃描會擷取一段滾動視窗（往前 60 天、往後 90 天），並記下 Google 的同步權杖；之後的掃描會帶上該權杖，只接收有變更的內容，這正是兩分鐘一次的頻率仍可負擔的原因。視窗每 24 小時會以一次完整同步重新定位，Google 每次使權杖失效時也是如此。

重新整理權杖存放於伺服器端的 secrets.json，位於伺服器的資料目錄下，僅限擁有者讀寫（0600）——不在作業系統鑰匙圈中，也永遠不會出現在用戶端裝置上。

連接多個帳戶

一個工作區可以連接多個 Google 帳戶（例如工作和個人帳戶）。為每個帳戶重複連接步驟；它們的活動會合併到相同的月／週／議程檢視中。每個帳戶各自獨立同步與重新整理，也可以各自中斷連線。

重新連線已過期的帳戶

如果 Google 永久使某個帳戶的權杖失效（工作階段被撤銷或長期過期），同步就會停止，Control Center 會在日曆上顯示重新連線橫幅，並發出桌面通知。點擊重新連線並核准新的代碼；下次同步成功後橫幅便會消失。

中斷連線帳戶

在日曆側邊欄（或設定 → 工作區 → 個人資料與身分）中，點擊該帳戶的中斷連線。這會刪除其已同步的活動，並清除伺服器上儲存的權杖。

從無介面伺服器連接

沒有接上圖形介面的伺服器，可以從自己的終端機連接同一個帳戶：

GOOGLE_OAUTH_CLIENT_ID=<id> GOOGLE_OAUTH_CLIENT_SECRET=<secret> \
  cc_server calendar connect --data-dir <dir> --workspace <workspace-id>

它會印出一組代碼和一個 URL，等待核准，然後儲存權杖，並在下一次掃描時同步。

從原始碼建置的版本不附帶 Google 用戶端，因此必須提供 ID 和密鑰——請設定 GOOGLE_OAUTH_CLIENT_ID 和 GOOGLE_OAUTH_CLIENT_SECRET。這裡沒有 --google-client-id 旗標（未知旗標會被忽略）。若缺少這對環境變數，指令會以缺少用戶端的錯誤結束。

自備 Google 用戶端（分支與自行託管）

已發行的組建會附帶 Google 用戶端，因此大多數人都不需要碰這一節。如果你是從原始碼建置、自行執行伺服器，或想讓同意畫面顯示你自己專案的名稱，才需要自備用戶端。

在 Google Cloud Console 中啟用 Google Calendar API，並設定 OAuth 同意畫面，加入 calendar.readonly、openid 和 email 範圍。應用程式尚未通過驗證時，請把自己加入為測試使用者。在同意畫面加入 calendar.events 並不會啟用 RSVP——Control Center 從不要求該範圍。
建立應用程式類型為 TVs and limited input devices 的 OAuth 用戶端 ID，並複製用戶端 ID 和用戶端密鑰。
你可以逐次連接提供它們（在對話框中選擇使用我自己的 Google Cloud 用戶端），或透過 GOOGLE_OAUTH_CLIENT_ID 和 GOOGLE_OAUTH_CLIENT_SECRET 在整個伺服器範圍提供。

伺服器範圍的一對憑證會全面取代內建的一對，包括「使用 Control Center 的 Google 應用程式」選項背後的憑證——因此在你自己的伺服器上，該選項用的就是你的應用程式。

用戶端密鑰永遠不會離開伺服器：沒有任何 RPC 回應會帶上它，而透過伺服器自己的用戶端連接的帳戶，只會儲存一個標記，而非該對憑證的副本，因此輪替密鑰只需以新值重新啟動。

疑難排解

症狀	可能原因
對話框沒有提供內建選項	此組建不附帶 Google 用戶端（原始碼建置），或伺服器啟動時只提供了該對憑證的其中一半。ID 和密鑰兩者都必須提供
啟動流程時出現 `invalid_scope`	該 Cloud 專案中的裝置代碼用戶端未獲准使用 Calendar。請改用回送或網頁用戶端專案
Google 傳回 `invalid_client`	該用戶端不是 TVs and limited input devices 用戶端，或 ID 與密鑰來自不同的用戶端
核准成功但同步內容為空	你的帳戶不是同意畫面上的測試使用者，或未獲授予 `calendar.readonly`
代碼在你核准之前就過期	裝置代碼的有效時間很短。請重新開始連接以取得新的代碼
RSVP 時出現「無法更新你的回覆」	這是預期情況：連接流程從不要求 `calendar.events`
同步停止，伺服器日誌中出現重新整理警告	該帳戶是以已不再設定的用戶端連接。請重新連線該帳戶，或還原該用戶端 ID 和密鑰