Kết nối Google Calendar

Hướng dẫn này chỉ cho bạn cách kết nối Google Calendar với một không gian làm việc. Việc này diễn ra theo từng không gian làm việc: nó đồng bộ sự kiện của không gian làm việc đó vào Control Center, ở chế độ chỉ đọc. Xem Lịch và lên lịch để có bức tranh đầy đủ.

Kết nối một tài khoản

1. Mở Lịch trên thanh bên.
2. Nhấp Thêm tài khoản lịch trên thanh bên của lịch. (Mục này cũng nằm tại Cài đặt → Không gian làm việc → Hồ sơ & danh tính, trong Google Calendar.)
3. Chọn cách ủy quyền:
   • Dùng app Google của Control Center — không cần thiết lập gì. Đây là mặc định khi bản dựng của bạn có kèm sẵn app này.
   • Dùng client Google Cloud của tôi — dán client id và secret từ dự án của riêng bạn (xem Tự mang theo client Google của bạn).
4. Nhấp Kết nối Google Calendar. Hộp thoại hiện một mã ngắn và liên kết tới trang thiết bị của Google.
5. Mở trang đó trên bất kỳ thiết bị nào, nhập mã và phê duyệt quyền truy cập được yêu cầu. Hộp thoại tự đóng và các sự kiện của bạn bắt đầu được đồng bộ.

Máy chủ, chứ không phải thiết bị của bạn, thực hiện trao đổi này và giữ refresh token thu được — đó là lý do mã được phê duyệt trên “bất kỳ thiết bị nào” thay vì cụ thể trong ứng dụng này.

Tài khoản chỉ được kết nối với không gian làm việc đang hoạt động. Chuyển không gian làm việc, bạn sẽ thấy lịch của không gian làm việc đó thay vào.

Luồng kết nối yêu cầu calendar.readonly cùng email của bạn — cùng các phạm vi cho cả app tích hợp sẵn và client bạn dán vào. Control Center đọc sự kiện; nó không tạo, sửa, xóa hay phản hồi lời mời trên Google.

Đồng bộ diễn ra thế nào

Máy chủ nắm lịch quét: nó quét tài khoản đã kết nối của mọi không gian làm việc hai phút một lần và ghi sự kiện vào cơ sở dữ liệu của không gian làm việc. Máy khách không bao giờ nói chuyện với Google — chúng đọc những gì máy chủ đã ghi.

Lần quét là tăng dần. Lần chạy đầu tiên cho mỗi lịch tải một cửa sổ trượt (60 ngày về trước, 90 ngày tới) và ghi lại token đồng bộ của Google; các lần sau trình token đó ra và chỉ nhận những gì đã thay đổi, nhờ vậy nhịp hai phút mới chấp nhận được. Cửa sổ được neo lại bằng một lần đồng bộ đầy đủ mỗi 24 giờ và mỗi khi Google vô hiệu hóa token.

Refresh token nằm ở phía máy chủ trong secrets.json dưới thư mục dữ liệu của máy chủ, được ghi với quyền chỉ chủ sở hữu (0600) — không nằm trong keychain của hệ điều hành và không bao giờ nằm trên thiết bị máy khách.

Kết nối nhiều tài khoản

Một không gian làm việc có thể kết nối nhiều tài khoản Google (chẳng hạn tài khoản công việc và tài khoản cá nhân). Lặp lại bước kết nối cho từng tài khoản; sự kiện của chúng được gộp vào cùng các chế độ xem tháng / tuần / lịch trình. Mỗi tài khoản đồng bộ và làm mới độc lập, và mỗi tài khoản có thể được ngắt kết nối riêng.

Kết nối lại một tài khoản đã hết hạn

Nếu Google vô hiệu hóa vĩnh viễn token của một tài khoản (phiên bị thu hồi hoặc hết hạn từ lâu), quá trình đồng bộ dừng lại và Control Center hiện banner Kết nối lại trên lịch, kèm một thông báo trên máy tính để bàn. Nhấp Kết nối lại và phê duyệt một mã mới; banner sẽ biến mất ở lần đồng bộ thành công kế tiếp.

Ngắt kết nối một tài khoản

Từ thanh bên của lịch (hoặc Cài đặt → Không gian làm việc → Hồ sơ & danh tính), nhấp Ngắt kết nối trên tài khoản. Thao tác này xóa các sự kiện đã đồng bộ và xóa token đã lưu của tài khoản trên máy chủ.

Kết nối từ một máy chủ không giao diện

Máy chủ không gắn giao diện đồ họa kết nối cùng tài khoản đó từ terminal của chính nó:

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

Nó in ra một mã và một URL, chờ phê duyệt, rồi lưu token và đồng bộ ở lần quét kế tiếp.

Bản dựng từ mã nguồn không kèm client Google nào, nên bắt buộc phải có id và secret — hãy đặt GOOGLE_OAUTH_CLIENT_ID và GOOGLE_OAUTH_CLIENT_SECRET. Không có cờ --google-client-id (các cờ không rõ bị bỏ qua). Nếu thiếu cặp biến môi trường, lệnh thoát với lỗi thiếu client.

Tự mang theo client Google của bạn (bản fork và tự lưu trữ)

Các bản phát hành có kèm sẵn một client Google, nên hầu hết mọi người không bao giờ cần tới phần này. Hãy tự mang theo client của bạn nếu bạn dựng từ mã nguồn, tự chạy máy chủ riêng, hoặc muốn màn hình đồng ý hiển thị tên dự án của chính bạn.

1. Trong Google Cloud Console, bật Google Calendar API và cấu hình OAuth consent screen, thêm các phạm vi calendar.readonly, openid và email. Khi app chưa được xác minh, hãy thêm chính bạn làm test user. Thêm calendar.events trên màn hình đồng ý không bật được RSVP — Control Center không bao giờ yêu cầu phạm vi đó.
2. Tạo một OAuth client ID với loại ứng dụng TVs and limited input devices và sao chép cả client id lẫn client secret.
3. Cung cấp chúng theo từng lần kết nối (chọn Dùng client Google Cloud của tôi trong hộp thoại) hoặc trên toàn máy chủ bằng GOOGLE_OAUTH_CLIENT_ID và GOOGLE_OAUTH_CLIENT_SECRET.

Một cặp đặt trên toàn máy chủ sẽ thay thế cặp tích hợp sẵn ở mọi nơi, kể cả đằng sau tùy chọn “dùng app Google của Control Center” — nên trên máy chủ của riêng bạn, tùy chọn đó chính là app của bạn.

Client secret không bao giờ rời khỏi máy chủ: không có phản hồi RPC nào mang nó theo, và một tài khoản được kết nối qua client của chính máy chủ sẽ lưu một dấu tham chiếu thay vì bản sao của cặp khóa, nên việc xoay khóa chỉ là khởi động lại với giá trị mới.

Xử lý sự cố

Triệu chứng	Nguyên nhân có thể
Hộp thoại không có tùy chọn tích hợp sẵn	Bản dựng này không kèm client Google nào (bản dựng từ mã nguồn), hoặc máy chủ được khởi động chỉ với một nửa của cặp khóa. Cả id lẫn secret đều bắt buộc
invalid_scope khi bắt đầu luồng	Calendar không được cho phép với máy khách mã thiết bị trong dự án Cloud đó. Hãy dùng dự án máy khách loopback hoặc web thay thế
invalid_client từ Google	Máy khách không thuộc loại TVs and limited input devices, hoặc id và secret đến từ hai máy khách khác nhau
Phê duyệt thành công nhưng đồng bộ trống	Tài khoản của bạn không phải test user trên màn hình đồng ý, hoặc calendar.readonly không được cấp
Mã hết hạn trước khi bạn phê duyệt	Mã thiết bị có thời hạn ngắn. Hãy bắt đầu kết nối lại để lấy mã mới
“Không thể cập nhật phản hồi của bạn” khi RSVP	Đúng như dự kiến: luồng kết nối không bao giờ yêu cầu calendar.events
Đồng bộ dừng lại kèm cảnh báo làm mới trong nhật ký máy chủ	Tài khoản được kết nối bằng một máy khách không còn được cấu hình nữa. Hãy kết nối lại tài khoản, hoặc khôi phục client id và secret đó

Hướng dẫn liên quan

• Ghi và tóm tắt một cuộc họp: biến một sự kiện thành bản ghi
• Chạy máy chủ không giao diện: nơi token và lịch đồng bộ nằm
• Thiết lập tích hợp GitHub

Khái niệm liên quan

• Lịch và lên lịch