連接 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>

它會顯示一組代碼與一個網址，等待核准，然後儲存權杖，並在下一次掃描時同步。

從原始碼建置的版本不會隨附 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 與密鑰