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

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

Видимость

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