확장 속성

일정 리소스 의 필드는 위치, 시작 시간 등 일정과 관련된 가장 일반적인 데이터를 다루지만 애플리케이션은 사용 사례와 관련된 추가 메타데이터를 저장할 수 있습니다. Calendar API는 확장 속성이라고 하는 숨겨진 키-값 쌍을 일정과 함께 설정하는 기능을 제공합니다. 확장 속성을 사용하면 외부 데이터베이스를 활용하지 않고도 일정에 대한 애플리케이션별 데이터를 쉽게 저장할 수 있습니다.

공개 상태

사용 가능한 확장 속성에는 비공개와 공유의 두 가지 유형이 있습니다. 공유 속성은 일정의 모든 참석자가 보고 수정할 수 있는 반면 비공개 속성은 참석자 한 명의 일정 '사본'에 설정됩니다. 더 구체적으로 말하면 비공개 속성은 요청에 사용된 calendarId 및 eventId에만 적용되는 반면 공유 속성은 요청에 사용된 calendarId와 관계없이 표시됩니다.

속성 추가 및 업데이트

확장 속성은 일정 리소스에 설정되며 다른 필드와 마찬가지로 삽입, 업데이트, 및 패치 요청에서 설정할 수 있습니다. 패치 요청을 사용하면 일부 속성을 조작하면서 다른 속성은 그대로 둘 수 있으므로 이 방법을 사용하는 것이 좋습니다. 동일한 키로 새 속성을 추가하면 동일한 키를 가진 기존 속성이 덮어쓰입니다. 다음 예에서는 비공개 속성을 설정하는 방법을 보여줍니다.

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

한도

  1. 속성 키의 최대 크기는 44자(영문 기준)이며 키가 더 긴 속성은 자동으로 삭제됩니다.
  2. 속성 값의 최대 크기는 1, 024자(영문 기준)이며 값이 더 긴 속성은 자동으로 잘립니다.
  3. 일정에는 최대 300개의 속성이 있을 수 있으며 총 크기는 최대 32KB(키 크기 + 값 크기)입니다. 이러한 300개의 속성에는 일정의 모든 '사본'에 걸쳐 공유 속성과 비공개 속성이 포함됩니다.