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

The fields of the Events resources cover the most common data associated with an event, such as location, start time, etc, but applications may want to store additional metadata specific to their use case. 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 объектов включают общие и частные объекты для всех «копий» мероприятия.