Thuộc tính mở rộng

Các trường của Tài nguyên sự kiện bao gồm những dữ liệu phổ biến nhất liên quan đến một sự kiện, chẳng hạn như vị trí, thời gian bắt đầu, v.v. Tuy nhiên, 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 mình. Calendar API cung cấp khả năng đặt các cặp khoá-giá trị ẩn cho 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ó hai loại thuộc tính mở rộng: riêng tư và dùng chung. Tất cả người tham dự sự kiện đều có thể thấy và chỉnh sửa các thuộc tính được chia sẻ, trong khi các thuộc tính riêng tư được đặt trên "bản sao" cục bộ của sự kiện đối với một người tham dự. Cụ thể hơn, các thuộc tính riêng tư dành riêng cho calendarId và eventId được dùng trong yêu cầu, trong khi các thuộc tính dùng chung sẽ xuất hiện bất kể calendarId nào được 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 các thuộc tính này trong yêu cầu chèn, cập nhật và vá. Bạn nên sử dụng các 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 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 khoá sẽ ghi đè mọi thuộc tính 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 cách tốt hơn là đưa ra yêu cầu vá để đặt giá trị thành rỗng. Ví dụ sau đây minh hoạ 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 các sự kiện dựa trên giá trị của các thuộc tính mở rộng bằng cách sử dụng yêu cầu Events.list. Đặt trường privateExtendedProperty hoặc sharedExtendedProperty thành một ràng buộc theo định dạng propertyName=value, tương ứng tìm kiếm theo các thuộc tính riêng tư và được chia sẻ. 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 ràng buộc được kết hợp 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 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

Xin lưu ý rằng các ràng buộc đối với tài sản riêng tư và tài sản dùng chung được kết hợp với nhau, do đó, các sự kiện phải khớp với cả hai nhóm ràng buộc thì mới đượ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á 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ó thông báo.
  2. Kích thước tối đa của giá trị thuộc tính là 1.024 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ó 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 lên đến 32 kB (kích thước khoá + kích thước giá trị). 300 thuộc tính này bao gồm cả thuộc tính dùng chung và thuộc tính riêng tư, trên tất cả các "bản sao" của sự kiện.