이벤트 리소스의 필드는 위치, 시작 시간 등 이벤트와 관련된 가장 일반적인 데이터를 포함하지만 애플리케이션에서는 사용 사례에 맞는 추가 메타데이터를 저장해야 할 수 있습니다. Calendar API는 확장 속성이라고 하는 이벤트와 함께 숨겨진 키-값 쌍을 설정하는 기능을 제공합니다. 확장 속성을 사용하면 외부 데이터베이스를 활용하지 않고도 이벤트의 애플리케이션별 데이터를 쉽게 저장할 수 있습니다.
공개 상태
사용 가능한 확장 속성에는 비공개 및 공유라는 두 가지 유형이 있습니다.
공유 속성은 이벤트의 모든 참석자가 보고 수정할 수 있는 반면 비공개 속성은 한 참석자의 이벤트 로컬 '사본'에 설정됩니다. 더 구체적으로 비공개 속성은 요청에 사용된 calendarId 및 eventId에만 적용되지만 공유 속성은 요청에 사용된 calendarId와 관계없이 표시됩니다.
속성 추가 및 업데이트
확장된 속성은 이벤트 리소스에 설정되며 다른 필드와 마찬가지로 insert, update, 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
이러한 필드를 여러 번 반복할 수 있고 제약 조건이 함께 OR로 연결되므로 이벤트는 반환될 제약 조건 중 하나와만 일치하면 됩니다.
다음 예에서는 비공개 속성 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
한도
- 속성 키의 최대 크기는 44자(영문 기준)이며 키가 더 긴 속성은 자동으로 삭제됩니다.
- 속성 값의 최대 크기는 1,024자(영문 기준)이며, 값이 더 긴 속성은 자동으로 잘립니다.
- 이벤트는 최대 300개의 속성(키 크기 + 값 크기)을 포함하여 총 32KB까지 포함할 수 있습니다. 이러한 300개의 속성에는 이벤트의 모든 '사본'에 걸친 공유 속성과 비공개 속성이 포함됩니다.