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

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. The Calendar API provides the ability to set hidden key-value pairs with an event, called extended properties . Extended properties make it easy to store application-specific data for an event without having to utilize an external database.

Видимость

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

Добавление и обновление свойств

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

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

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

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

Все свойства, не включенные в запрос на обновление, будут удалены, но лучше использовать запрос на исправление (patch request), чтобы установить значение равным 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

Обратите внимание, что ограничения для частных и общих свойств объединяются с помощью логической операции И, поэтому события должны соответствовать обоим наборам ограничений, чтобы быть возвращенными. В следующем примере находятся события с частным свойством 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 объектов включают как общие, так и частные объекты во всех «копиях» события.