Các trường của Tài nguyên sự kiện bao gồm dữ liệu phổ biến nhất liên kết với một sự kiện, chẳng hạn như vị trí, thời gian bắt đầu, v.v. nhưng các ứng dụng có thể cần lưu trữ thêm siêu dữ liệu cho trường hợp sử dụng của chúng. API Lịch cho phép đặt các cặp khoá-giá trị ẩn bằng một sự kiện, được gọi là thuộc tính mở rộng. Các thuộc tính mở rộng giúp bạn dễ dàng lưu trữ dữ liệu dành riêng cho ứng dụng cho một sự kiện mà không cần phải sử dụng cơ sở dữ liệu bên ngoài.
Chế độ hiển thị
Có 2 loại tài sản mở rộng: riêng tư và dùng chung.
Tất cả người tham dự một sự kiện đều có thể xem và chỉnh sửa các thuộc tính dùng chung, còn thuộc tính riêng tư được thiết lập trên "bản sao" cục bộ của sự kiện của một người tham dự. Cụ thể hơn, các thuộc tính riêng tư là dành riêng cho calendarId và eventId được sử dụng trong yêu cầu, trong khi các thuộc tính dùng chung sẽ hiển thị bất kể calendarId được sử dụng trong yêu cầu là gì.
Thêm và cập nhật cơ sở lưu trú
Thuộc tính mở rộng được đặt trên tài nguyên Sự kiện, và giống như các trường khác, bạn có thể thiết lập các trường khác trong các yêu cầu insert, update và patch (bản vá). Sử dụng yêu cầu bản vá là phương thức ưu tiên, vì phương thức này cho phép bạn thao tác với một số thuộc tính trong khi vẫn giữ nguyên các thuộc tính khác. Việc thêm một thuộc tính mới có cùng một khoá sẽ ghi đè mọi thuộc tính hiện có bằng cùng một khoá. Ví dụ sau đây cho thấy cách thiết lập một thuộc tính riêng tư:
PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
{
"extendedProperties": {
"private": {
"petsAllowed": "yes"
}
}
}
Xoá tài sản
Mọi thuộc tính không có trong yêu cầu cập nhật sẽ bị xoá, nhưng một phương pháp hay hơn là tạo yêu cầu bản vá để đặt giá trị thành rỗng. Ví dụ sau đây sẽ minh hoạ việc xoá một tài sản riêng tư:
PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
{
"extendedProperties": {
"private": {
"petsAllowed": null
}
}
}
Tìm cơ sở lưu trú
Bạn có thể tìm kiếm sự kiện dựa trên giá trị trên các thuộc tính mở rộng của sự kiện đó bằng cách sử dụng yêu cầu
Events.list.
Đặt trường privateExtendedProperty hoặc sharedExtendedProperty thành một quy tắc ràng buộc ở định dạng propertyName=value, có thể tìm kiếm các thuộc tính riêng tư và thuộc tính dùng chung tương ứng. Ví dụ sau đây trả về các sự kiện có thuộc tính riêng tư petsAllowed=yes:
GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
?privateExtendedProperty=petsAllowed%3Dyes
Bạn có thể lặp lại các trường này nhiều lần và các điều kiện ràng buộc được kết hợp với nhau, vì vậy, các sự kiện chỉ cần khớp với một trong các điều kiện ràng buộc sẽ được trả về.
Ví dụ sau đây tìm các sự kiện có thuộc tính private petsAllowed=yes hoặc isOutside=yes:
GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
?privateExtendedProperty=petsAllowed%3Dyes
&privateExtendedProperty=isOutside%3Dyes
Tuy nhiên, xin lưu ý rằng các điều kiện ràng buộc đối với thuộc tính riêng tư và thuộc tính dùng chung thì được kết hợp với nhau, vì vậy, để được trả về, sự kiện phải khớp với cả hai nhóm điều kiện ràng buộc.
Ví dụ sau đây tìm các sự kiện có thuộc tính riêng tư petsAllowed=yes và thuộc tính công khai createdBy=myApp:
GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
?privateExtendedProperty=petsAllowed%3Dyes
&sharedExtendedProperty=createdBy%3DmyApp
Các giới hạn
- Kích thước tối đa của khoá của một thuộc tính là 44 ký tự và các thuộc tính có khoá dài hơn sẽ tự động bị loại bỏ.
- Kích thước tối đa của một giá trị thuộc tính là 1024 ký tự và các thuộc tính có giá trị dài hơn sẽ tự động bị cắt bớt.
- Một sự kiện có thể có tối đa 300 thuộc tính với tổng kích thước lên tới 32kB (kích thước khoá + kích thước giá trị). 300 thuộc tính này bao gồm các tài sản dùng chung và riêng tư, trên tất cả các "bản sao" của sự kiện.