Thuộc tính mở rộng

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ể muốn lưu trữ siêu dữ liệu bổ sung dành riêng cho trường hợp sử dụng của chúng. API Lịch cung cấp khả năng đặ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 sử dụng cơ sở dữ liệu bên ngoài.

Chế độ hiển thị

Có hai loại tài sản mở rộng: riêng tư và dùng chung. Tất cả người tham dự sự kiện đều có thể xem và chỉnh sửa thuộc tính dùng chung, còn thuộc tính riêng tư được đặt trên "bản sao" cục bộ của một người tham dự sự kiện. Cụ thể hơn, các thuộc tính riêng tư 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.

Thêm và cập nhật cơ sở lưu trú

Các 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ể đặt thuộc tính này trong các yêu cầu chèn, cập nhật và bản vá. Bạn nên sử dụng yêu cầu vá vì phương thức này cho phép bạn thao tác một số thuộc tính mà không làm ảnh hưởng đến các thuộc tính khác. Việc thêm một tài sản mới có cùng khoá sẽ ghi đè mọi tài sản hiện có có cùng khoá. Ví dụ sau đây cho thấy cách đặt 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 tốt hơn là bạn nên tạo yêu cầu vá để đặt giá trị thành rỗng. Ví dụ sau đây cho thấy cách xoá một thuộc tính riêng tư:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId
 
{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

Thuộc tính tìm kiếm

Bạn có thể tìm kiếm sự kiện dựa trên các 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. Quy tắc này sẽ tìm kiếm tương ứng với các thuộc tính riêng tư và thuộc tính dùng chung. 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 quy tắc ràng buộc được nối với nhau bằng toán tử OR, vì vậy, các sự kiện chỉ cần khớp với một trong các quy tắc ràng buộc để được trả về. Ví dụ sau đây tìm các sự kiện có thuộc tính riêng tư 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 quy tắc ràng buộc đối với các thuộc tính riêng tư và được chia sẻ được kết hợp với nhau bằng toán tử AND, vì vậy, các sự kiện phải khớp với cả hai nhóm quy tắc ràng buộc để được trả về. 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

Giới hạn

  1. 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ẽ bị loại bỏ mà không cần thông báo.
  2. Kích thước tối đa của 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ẽ bị cắt bớt mà không cần thông báo.
  3. Một sự kiện có thể có tối đa 300 thuộc tính với tổng kích thước tối đa là 32 kB (kích thước khoá + kích thước giá trị). 300 thuộc tính này bao gồm các thuộc tính dùng chung và thuộc tính riêng tư trên tất cả "bản sao" của sự kiện.