Расширенные свойства

Поля ресурсов «События» охватывают наиболее распространенные данные, связанные с событием, такие как местоположение, время начала и т. д., но приложениям может потребоваться хранить дополнительные метаданные, специфичные для их варианта использования. API календаря предоставляет возможность устанавливать скрытые пары «ключ-значение» с событием, называемым расширенными свойствами . Расширенные свойства упрощают хранение данных о событии, специфичных для приложения, без необходимости использования внешней базы данных.

Видимость

Доступны два типа расширенных свойств: частные и общие. Общие свойства видны и доступны для редактирования всем участникам мероприятия, тогда как частные свойства устанавливаются в локальной «копии» мероприятия одного участника. Более конкретно, частные свойства относятся к calendarId и eventId , используемым в запросе, тогда как общие свойства будут отображаться независимо от calendarId используемого в запросе.

Добавить и обновить свойства

Расширенные свойства задаются для ресурса Events и, как и другие поля, могут быть установлены в запросах на вставку , обновление и исправление . Использование запросов на исправления является предпочтительным методом, поскольку позволяет манипулировать некоторыми свойствами, оставляя другие нетронутыми. Добавление нового свойства с тем же ключом перезапишет все существующие свойства с тем же ключом. В следующем примере показана установка частного свойства:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": "yes"
    }
  }
}

Удалить свойства

Любые свойства, не включенные в запрос на обновление, будут удалены, но лучший подход — сделать запрос на исправление, чтобы установить значение null. В следующем примере показано удаление частной собственности:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

Поиск недвижимости

Вы можете искать события на основе значений их расширенных свойств, используя запрос Events.list . Установите для поля PrivateExtendedProperty или SharedExtendedProperty ограничение в формате propertyName=value , которое выполняет поиск по частным и общим свойствам соответственно. Следующий пример возвращает события с частным свойством petsAllowed=yes :

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes

Вы можете повторять эти поля несколько раз, а ограничения объединяются по логическому оператору ИЛИ, поэтому события должны соответствовать только одному из ограничений, которые будут возвращены. В следующем примере выполняется поиск событий с частным свойством petsAllowed=yes или isOutside=yes :

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &privateExtendedProperty=isOutside%3Dyes

Однако помните, что ограничения на частные и общие свойства объединяются оператором AND, поэтому для возврата события должны соответствовать обоим наборам ограничений. В следующем примере выполняется поиск событий с частным свойством petsAllowed=yes и общедоступным свойством createdBy=myApp :

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &sharedExtendedProperty=createdBy%3DmyApp

Пределы

1. Максимальный размер ключа свойства — 44 символа, а свойства с более длинными ключами будут автоматически удалены.
2. Максимальный размер значения свойства — 1024 символа, а свойства с более длинными значениями будут автоматически усекаться.
3. Событие может иметь до 300 свойств общим размером до 32 КБ (размер ключей + размер значения). Эти 300 объектов включают общие и частные объекты для всех «копий» мероприятия.