Hướng dẫn này mô tả lịch, sự kiện và mối quan hệ giữa chúng.
Lịch
Lịch là tập hợp các sự kiện có liên quan cùng với siêu dữ liệu bổ sung chẳng hạn như tóm tắt, múi giờ mặc định, vị trí, v.v. Mỗi lịch được xác định theo địa chỉ email. Các lịch có thể có nhiều chủ sở hữu.
Sự kiện
Sự kiện là một đối tượng được liên kết với phạm vi ngày hoặc thời gian cụ thể. Các sự kiện được xác định bằng một mã nhận dạng duy nhất. Ngoài điểm bắt đầu và ngày kết thúc, sự kiện chứa dữ liệu khác như thông tin tóm tắt, 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 một và định kỳ:
- Một sự kiện duy nhất thể hiện 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 lên lịch hoặc cả ngày:
- Một sự kiện được tính giờ xảy ra giữa hai thời điểm cụ thể. Sự kiện có dấu thời gian
sử dụng các trường
start.dateTime
vàend.dateTime
để chỉ định thời điểm xảy ra. - Một sự kiện cả ngày kéo dài cả ngày hoặc một chuỗi ngày liên tiếp. Cả ngày
các sự kiện sử dụng trường
start.date
vàend.date
để chỉ định thời điểm chúng xảy ra. Lưu ý rằng trường múi giờ không có ý nghĩa đối với các sự kiện cả ngày.
Người tổ chức
Các sự kiện có một trình tổ chức duy nhất 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ự. Người tham dự thường là lịch chính của người dùng được mời.
Sơ đồ dưới đây thể hiện mối quan hệ khái niệm giữa các lịch, sự kiện và các phần tử có liên quan khác:
Lịch chính & 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 lịch 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ã nhận dạng thường khớp với địa chỉ email chính của người dùng. Miễn là có tài khoản nào đó, thì lịch chính của tài khoản đó sẽ tuyệt đối không bị xoá hoặc lịch biểu "không được sở hữu" theo người dùng. 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ể tạo bất kỳ số lượng nào các lịch khác; những lịch này có thể được sửa đổi, xoá và chia sẻ giữa 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ó. Có thể dùng mật khẩu này để tạo và xoá lịch. Bạn cũng có thể truy xuất hoặc đặt các tài sản chung được chia sẻ trên tất cả người dùng có quyền truy cập vào lịch. Ví dụ: tiêu đề và chế độ mặc định của lịch múi giờ là các thuộc tính toàn cầu.
CalendarList là một tập hợp tất cả các mục trong 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 trang doanh nghiệp này để thêm và xoá cụm từ tìm kiếm hiện có lịch đến/từ danh sách người dùng. Bạn cũng sử dụng tệp này để truy xuất và đặt giá trị của các thuộc tính lịch dành riêng cho người dùng, chẳng hạn như lời nhắc mặc định. Khác Ví dụ: màu nền trước, vì mỗi người dùng có thể có màu khác nhau đặt cho cùng một lịch.
Bảng sau đây so sánh ý nghĩa của các toán tử đố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 đã thêm vào danh sách lịch của nhà sáng 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 thông tin tuỳ chỉnh dành riêng cho người dùng chẳng hạn như chọn màu hoặc ghi đè lời nhắc. |
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 dành riêng cho người dùng. |
Sự kiện định kỳ
Một số sự kiện diễn ra nhiều lần theo lịch trình định kỳ, chẳng hạn như cuộc họp hằng tuần, ngày sinh nhật và ngày lễ. Ngoài việc có 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 một lần là sự kiện không định kỳ và chỉ diễn ra một lần.
Quy tắc lặp lại
Lịch biểu cho một sự kiện định kỳ được xác định trong hai phần:
Trường bắt đầu và trường kết thúc (xác định lần xuất hiện đầu tiên như thể đây là chỉ một sự kiện độc lập) và
Trường lặp lại (xác định cách sự kiện lặp lại 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 một vài
Các thuộc tính RRULE
, RDATE
hoặc EXDATE
như định nghĩa trong RFC
5545.
Thuộc tính RRULE
là quan trọng nhất vì nó xác định quy tắc thông thường cho
lặp lại sự kiện. Nó bao gồm một số thành phần. Một số tín hiệu trong số đó là:
FREQ
– Tần suất lặp lại sự kiện (chẳng hạn nhưDAILY
hoặcWEEKLY
). Bắt buộc.INTERVAL
— Hoạt động cùng vớiFREQ
để chỉ định tần suất sự kiện lặp lại. Ví dụ:FREQ=DAILY;INTERVAL=2
có nghĩa là một lần mỗi 2 ngày.COUNT
— Số lần sự kiện này lặp lại.UNTIL
– Ngày hoặc giờ cho đến khi sự kiện được lặp lại (bao gồm cả ngày đó).BYDAY
— Ngày trong tuần mà sự kiện lặp lại (SU
,MO
,TU
, v.v.). Các thành phần tương tự khác bao gồmBYMONTH
,BYYEARDAY
vàBYHOUR
.
Thuộc tính RDATE
chỉ định ngày hoặc giờ bổ sung khi sự kiện
có thể xảy ra. Ví dụ: RDATE;VALUE=DATE:19970101,19970120
.
Sử dụng phương thức này để thêm các lần xuất hiện khác không có trong RRULE
.
Thuộc tính EXDATE
tương tự như RDATE, nhưng chỉ định ngày hoặc giờ
khi sự kiện không xảy ra. Điều đó có nghĩa là những lần xuất hiện đó
bị loại trừ. Giá trị này phải trỏ đến một thực thể hợp lệ do quy tắc lặp lại tạo ra.
EXDATE
và RDATE
có thể có múi giờ và phải là ngày (không phải là ngày-giờ)
cho các sự kiện kéo dài 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à tập hợp của tất cả quy tắc RRULE
và RDATE
, trừ đi phương thức
những mục bị tất cả EXDATE
quy tắc loại trừ.
Dưới đây là một số ví dụ về sự kiện định kỳ:
Sự kiện sẽ diễn ra từ 6 giờ sáng đến 7 giờ sáng từ thứ Ba và thứ Sáu hằng tuần, bắt đầu từ từ ngày 15/9/2015 và ngừng sau lần thứ 5 vào ngày 29/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" ], …
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 suốt tháng, 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à ngoại lệ
Một sự kiện định kỳ bao gồm một số trường hợp: các lần xuất hiện cụ thể của sự kiện đó vào những thời điểm khác nhau. Những thực thể này đóng vai trò là 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 lần xuất hiện của sự kiện đó) hoặc chỉ các lần diễn ra riêng lẻ. Những trường hợp khác với sự kiện gốc định kỳ được gọi là ngoại lệ.
Ví dụ: một ngoại lệ có thể có bản tóm tắt khác, thời gian bắt đầu khác,
hoặc những người tham dự khác chỉ được mời vào trường hợp đó. Bạn cũng có thể huỷ
mà không cần loại bỏ sự kiện định kỳ
(việc huỷ thực thể được phản ánh trong sự kiện
status
).
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 Bạn có thể tìm thấy API Lịch Google tại đây.
Múi giờ
Múi giờ chỉ định một khu vực áp dụng 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 theo 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 mô tả tác động của các chế độ cài đặt này.
Múi giờ lịch
Múi giờ của lịch còn được gọi là múi giờ mặc định do
tác động của nó đối với kết quả truy vấn. Múi giờ theo lịch ảnh hưởng đến cách
các giá trị thời gian được thông dịch hoặc trình bày bởi
events.get()
!
events.list()
và
events.instances()
.
- Chuyển đổi múi giờ của kết quả truy vấn
- Kết quả của
get()
,list()
vàinstances()
được trả về theo múi giờ mà bạn chỉ định trongtimeZone
. Nếu bạn bỏ qua thông số này, thì tất cả các phương thức này đều sử dụng lịch làm múi giờ mặc định. - Khớp sự kiện cả ngày với truy vấn có giới hạn thời gian
- Các
list()
vàinstances()
cho phép bạn chỉ định bộ lọc thời gian bắt đầu và thời gian kết thúc bằng 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 được dùng để tính 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 chúng có thuộc thông số kỹ thuật của bộ lọc hay không.
Múi giờ của sự kiện
Các phiên bản 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 các thời điểm này có thể bao gồm múi giờ. Bạn có thể chỉ định múi giờ theo một số cách; thời gian sau đây đều chỉ định cùng một lúc:
- Thêm giá trị chênh lệch múi giờ vào trường
dateTime
, ví dụ:2017-01-25T09:00:00-0500
. - Chỉ định giờ mà không có chênh lệch, ví dụ:
2017-01-25T09:00:00
, để trống trườngtimeZone
(giá trị này ngầm sử dụng múi giờ mặc định). - Chỉ định giờ mà không có chênh lệch, ví dụ:
2017-01-25T09:00:00
, nhưng sử dụng trườngtimeZone
để 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 giá trị chênh lệch bằng 02017-01-25T14:00:00+0000
.
Cách trình bày nội bộ về thời gian diễn ra sự kiện đều giống 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ờ vào sự kiện, giống như
khi bạn đặt múi giờ cho sự kiện bằng Lịch
Giao diện người dùng:
Múi giờ của sự kiện định kỳ
Đối với các sự kiện định kỳ, bạn phải luôn chỉ định một múi giờ duy nhất. Điều này là cần thiết để mở rộng thời gian lặp lại của sự kiện.