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

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

Видимость

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

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

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

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

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