Lịch và sự kiện

Hướng dẫn này mô tả lịch, sự kiện và mối quan hệ của chúng với nhau.

Lịch

Lịch là một tập hợp các sự kiện có liên quan, cùng với siêu dữ liệu bổ sung như thông tin tóm tắt, múi giờ mặc định, vị trí, v.v. Mỗi lịch được xác định bằng một mã nhận dạng là địa chỉ email. Lịch có thể có nhiều chủ sở hữu.

Sự kiện

Sự kiện là đối tượng được liên kết với một phạm vi ngày hoặc giờ cụ thể. Sự kiện được xác định bằng một mã nhận dạng duy nhất. Ngoài ngày bắt đầu và ngày kết thúc, sự kiện còn chứa các dữ liệu khác như bản tóm tắt, nội dung mô tả, vị trí, trạng thái, lời nhắc, tệp đính kèm, v.v.

Các loại sự kiện

Lịch Google hỗ trợ các sự kiện đơnđịnh kỳ:

  • Mỗi sự kiện đại diện cho một lần xuất hiện duy nhất.
  • Sự kiện định kỳ xác định nhiều lần xuất hiện.

Sự kiện cũng có thể được đặt thời gian hoặc cả ngày:

  • Sự kiện được tính giờ xảy ra giữa hai thời điểm cụ thể. Các sự kiện được tính thời gian sử dụng các trường start.dateTimeend.dateTime để chỉ định thời điểm các sự kiện đó xảy ra.
  • Sự kiện cả ngày kéo dài toàn bộ ngày hoặc một chuỗi ngày liên tiếp. Các sự kiện cả ngày sử dụng các trường start.dateend.date để chỉ định thời điểm các sự kiện đó xảy ra. Lưu ý rằng trường múi giờ không có ý nghĩa nào đối với các sự kiện cả ngày.

Người tổ chức

Các sự kiện có một người tổ chức duy nhất, tức là lịch chứa bản sao chính của sự kiện. Sự kiện cũng có thể có nhiều người tham dự. Một người tham dự thường là lịch chính của người dùng được mời.

Sơ đồ sau đây cho thấy mối quan hệ khái niệm giữa lịch, sự kiện và các phần tử liên quan khác:

Lịch chính và các lịch khác

Lịch chính là một loại lịch đặc biệt được liên kết với một tài khoản người dùng. Lịch này được tạo tự động cho mỗi tài khoản người dùng mới và mã lịch thường khớp với địa chỉ email chính của người dùng. Miễn là tài khoản đó tồn tại, người dùng sẽ không bao giờ có thể xoá hoặc "không sở hữu" lịch chính của tài khoản đó. Tuy nhiên, bạn vẫn có thể chia sẻ tệp này với những người dùng khác.

Ngoài lịch chính, bạn có thể rõ ràng tạo bất kỳ số lượng lịch nào khác; các lịch này có thể được sửa đổi, xóa và chia sẻ cho nhiều người dùng.

Lịch và danh sách lịch

Bộ sưu tập Lịch đại diện cho tất cả các lịch hiện có. Bạn có thể dùng lịch này để tạo và xoá lịch. Bạn cũng có thể truy xuất hoặc đặt các thuộc tính chung được chia sẻ cho tất cả người dùng có quyền truy cập vào lịch. Ví dụ: tiêu đề và múi giờ mặc định của lịch là các thuộc tính chung.

CalendarList là một tập hợp tất cả các mục trên lịch mà người dùng đã thêm vào danh sách của họ (hiển thị trong bảng điều khiển bên trái của giao diện người dùng web). Bạn có thể sử dụng lịch này để thêm và xoá các lịch hiện có khỏi danh sách người dùng. Bạn cũng sử dụng thuộc tính này để truy xuất và đặt giá trị của các thuộc tính lịch của người dùng cụ thể, chẳng hạn như lời nhắc mặc định. Một ví dụ khác là màu nền trước, vì mỗi người dùng có thể có các màu khác nhau được đặt cho cùng một lịch.

Bảng sau đây so sánh ý nghĩa của các thao tác đối với hai tập hợp:

Hoạt động Lịch CalendarList
insert Tạo lịch phụ mới. Theo mặc định, lịch này cũng được thêm vào danh sách lịch của người tạo. Chèn lịch hiện có vào danh sách của người dùng.
delete Xoá lịch phụ. Xoá lịch khỏi danh sách của người dùng.
get Truy xuất siêu dữ liệu lịch, ví dụ: tiêu đề, múi giờ. Truy xuất siêu dữ liệu cùng với tuỳ chỉnh theo từng người dùng cụ thể, chẳng hạn như lời nhắc ghi đè hoặc màu.
patch/update Sửa đổi siêu dữ liệu của lịch. Sửa đổi các thuộc tính lịch của người dùng cụ thể.

Sự kiện định kỳ

Một số sự kiện diễn ra nhiều lần theo lịch định kỳ, chẳng hạn như cuộc họp hằng tuần, sinh nhật và ngày lễ. Ngoại trừ thời gian bắt đầu và kết thúc khác nhau, các sự kiện lặp lại này thường giống hệt nhau.

Các sự kiện được gọi là định kỳ nếu các sự kiện đó lặp lại theo một lịch biểu đã xác định. Sự kiện đơn lẻ là không định kỳ và chỉ xảy ra một lần.

Quy tắc định kỳ

Lịch biểu cho một sự kiện định kỳ được xác định trong hai phần:

  • Các trường bắt đầu và kết thúc của sự kiện (xác định lần xuất hiện đầu tiên, như thể đây chỉ là một sự kiện đơn lẻ độc lập), và

  • Trường lặp lại (xác định cách lặp lại sự kiện theo thời gian).

Trường lặp lại chứa một mảng chuỗi đại diện cho một hoặc nhiều thuộc tính RRULE, RDATE hoặc EXDATE như đã xác định trong RFC 5545.

Thuộc tính RRULE là quan trọng nhất vì thuộc tính này xác định một quy tắc thông thường để lặp lại sự kiện. Lớp này bao gồm một số thành phần. Có thể kể đến một số ví dụ như sau:

  • FREQ – Tần suất lặp lại sự kiện (chẳng hạn như DAILY hoặc WEEKLY). Bắt buộc.

  • INTERVAL – Hoạt động cùng với FREQ để chỉ định tần suất lặp lại sự kiện. Ví dụ: FREQ=DAILY;INTERVAL=2 có nghĩa là 2 ngày một lần.

  • COUNT – Số lần sự kiện này sẽ được lặp lại.

  • UNTIL – Ngày hoặc giờ mà sự kiện sẽ được lặp lại (bao gồm cả ngày này).

  • BYDAY – Ngày trong tuần mà sự kiện sẽ được lặp lại (SU, MO, TU, v.v.). Các thành phần tương tự khác bao gồm BYMONTH, BYYEARDAYBYHOUR.

Thuộc tính RDATE chỉ định ngày hoặc giờ bổ sung khi sự kiện xảy ra. Ví dụ: RDATE;VALUE=DATE:19970101,19970120. Sử dụng hàm này để thêm các lần xuất hiện khác không thuộc phạm vi của RRULE.

Thuộc tính EXDATE tương tự như RDATE, nhưng chỉ định ngày hoặc giờ mà sự kiện không xảy ra. Điều này nghĩa là bạn phải loại trừ những lần xuất hiện đó. Thuộc tính này phải trỏ đến một thực thể hợp lệ do quy tắc lặp lại tạo.

EXDATERDATE có thể có múi giờ và phải là ngày (không phải ngày giờ) cho các sự kiện cả ngày.

Mỗi thuộc tính có thể xuất hiện trong trường lặp lại nhiều lần. Việc lặp lại được định nghĩa là hợp nhất của tất cả quy tắc RRULERDATE, trừ đi các quy tắc bị loại trừ trong tất cả quy tắc EXDATE.

Sau đây là một số ví dụ về các sự kiện định kỳ:

  1. Một sự kiện xảy ra từ 6 giờ sáng đến 7 giờ sáng vào thứ Ba và thứ Sáu hằng tuần, bắt đầu từ ngày 15 tháng 9 năm 2015 và kết thúc sau lần thứ 5 xảy ra vào ngày 29 tháng 9:

    ...
    "start": {
     "dateTime": "2015-09-15T06:00:00+02:00",
     "timeZone": "Europe/Zurich"
    },
    "end": {
     "dateTime": "2015-09-15T07:00:00+02:00",
     "timeZone": "Europe/Zurich"
    },
    "recurrence": [
     "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
    ],
    …
    
  2. Một sự kiện cả ngày bắt đầu từ ngày 1 tháng 6 năm 2015 và lặp lại 3 ngày một lần trong cả tháng, ngoại trừ ngày 10 tháng 6 nhưng bao gồm cả ngày 9 và 11 tháng 6:

    ...
    "start": {
     "date": "2015-06-01"
    },
    "end": {
     "date": "2015-06-02"
    },
    "recurrence": [
     "EXDATE;VALUE=DATE:20150610",
     "RDATE;VALUE=DATE:20150609,20150611",
     "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
    ],
    …
    

Trường hợp và trường hợp ngoại lệ

Sự kiện định kỳ bao gồm một số phiên bản: lần xuất hiện cụ thể của sự kiện đó tại các thời điểm khác nhau. Những thực thể này tự hoạt động như các sự kiện.

Việc sửa đổi sự kiện định kỳ có thể ảnh hưởng đến toàn bộ sự kiện định kỳ (và tất cả các bản sao của sự kiện đó) hoặc chỉ ảnh hưởng đến từng thực thể riêng lẻ. Những thực thể khác với sự kiện định kỳ gốc được gọi là ngoại lệ.

Ví dụ: trường hợp ngoại lệ có thể có một bản tóm tắt khác, thời gian bắt đầu khác hoặc những người tham dự bổ sung chỉ được mời vào phiên bản đó. Bạn cũng có thể huỷ hoàn toàn một thực thể mà không cần xoá sự kiện định kỳ đó (các lượt huỷ thực thể sẽ được phản ánh trong sự kiện status).

Bạn có thể tìm thấy các ví dụ về cách làm việc với các sự kiện và bản sao định kỳ thông qua API Lịch Google tại đây.

Múi giờ

Múi giờ xác định một vùng có giờ chuẩn thống nhất. Trong API Lịch Google, bạn chỉ định múi giờ bằng cách sử dụng giá trị nhận dạng múi giờ IANA.

Bạn có thể đặt múi giờ cho cả lịch và sự kiện. Các phần sau đây mô tả tác dụng của các chế độ cài đặt này.

Múi giờ của lịch

Múi giờ của lịch còn được gọi là múi giờ mặc định do ảnh hưởng đến kết quả truy vấn. Múi giờ của lịch ảnh hưởng đến cách các phương thức events.get(), events.list()events.instances() diễn giải hoặc trình bày giá trị thời gian.

Lượt chuyển đổi theo múi giờ của kết quả truy vấn
Kết quả của các phương thức get(), list()instances() được trả về theo múi giờ mà bạn chỉ định trong tham số timeZone. Nếu bạn bỏ qua tham số này, thì tất cả các phương thức này sẽ dùng múi giờ của lịch làm mặc định.
So khớp các sự kiện cả ngày với truy vấn tiết kiệm thời gian
Phương thức list()instances() cho phép bạn chỉ định các bộ lọc thời gian bắt đầu và thời gian kết thúc, trong đó phương thức trả về các thực thể nằm trong phạm vi đã chỉ định. Múi giờ theo lịch dùng để tính toán thời gian bắt đầu và thời gian kết thúc của các sự kiện cả ngày nhằm xác định xem các sự kiện đó có thuộc quy cách của bộ lọc hay không.

Múi giờ của sự kiện

Các thực thể sự kiện có thời gian bắt đầu và thời gian kết thúc; thông số kỹ thuật cho thời gian này có thể bao gồm cả múi giờ. Bạn có thể chỉ định múi giờ theo nhiều cách; các cách sau đây đều chỉ định cùng một thời gian:

  • Thêm phần chênh lệch múi giờ vào trường dateTime, ví dụ: 2017-01-25T09:00:00-0500.
  • Chỉ định thời gian không có chênh lệch, ví dụ: 2017-01-25T09:00:00, để trống trường timeZone (tức là ngầm sử dụng múi giờ mặc định).
  • Hãy chỉ định thời gian không có chênh lệch, ví dụ: 2017-01-25T09:00:00, nhưng sử dụng trường timeZone để chỉ định múi giờ.

Bạn cũng có thể chỉ định thời gian diễn ra sự kiện theo giờ UTC nếu muốn:

  • Hãy chỉ định thời gian theo giờ UTC: 2017-01-25T14:00:00Z hoặc sử dụng 2017-01-25T14:00:00+0000 chênh lệch bằng 0.

Giá trị biểu thị nội bộ của thời gian sự kiện là như nhau trong tất cả các trường hợp này, nhưng việc đặt trường timeZone sẽ đính kèm múi giờ cho sự kiện, giống như khi bạn đặt múi giờ của sự kiện bằng giao diện người dùng Lịch:

Mảnh ảnh chụp màn hình cho thấy múi giờ của một sự kiện

Múi giờ của sự kiện định kỳ

Đối với sự kiện định kỳ, bạn phải luôn chỉ định múi giờ duy nhất. Cần có giá trị này để mở rộng tần suất lặp lại của sự kiện.