캘린더 및 일정

이 가이드에서는 캘린더, 일정, 캘린더와 일정의 관계를 설명합니다.

캘린더

캘린더는 요약, 기본 시간대, 위치 등 추가 메타데이터와 함께 관련 일정의 모음입니다. 각 캘린더는 이메일 주소인 ID로 식별됩니다. 캘린더는 다른 사용자와 공유할 수 있습니다. 기본 캘린더는 연결된 사용자 계정의 소유이며, 다른 캘린더는 단일 데이터 소유자의 소유입니다.

일정

일정은 특정 날짜 또는 시간 범위와 연결된 객체입니다. 일정은 고유 ID로 식별됩니다. 일정에는 시작 및 종료 날짜/시간 외에도 요약, 설명, 위치, 상태, 리마인더, 첨부파일 등의 데이터가 포함됩니다.

일정 유형

Google Calendar는 단일 일정과 반복 일정을 지원합니다.

• 단일 일정은 고유한 발생을 나타냅니다.
• 반복 일정은 여러 발생을 정의합니다.

일정은 시간 지정 또는 종일 일 수도 있습니다.

• 시간 지정 일정은 두 특정 시점 사이에 발생합니다. 시간 지정 일정은 start.dateTime 및 end.dateTime 필드를 사용하여 발생 시점을 지정합니다.
• 종일 일정은 하루 전체 또는 연속되는 여러 날에 걸쳐 진행됩니다. 종일 일정은 start.date 및 end.date 필드를 사용하여 발생 시점을 지정합니다. 시간대 필드는 종일 일정과 관련이 없습니다.

일정의 시작과 종료는 모두 시간 지정 또는 모두 종일이어야 합니다. 예를 들어 start.date와 end.dateTime을 지정하는 것은 유효하지 않습니다.

주최자

일정에는 일정의 기본 사본이 포함된 캘린더인 단일 주최자 가 있습니다. 일정에는 여러 참석자가 있을 수도 있습니다. 참석자는 일반적으로 초대된 사용자의 기본 캘린더입니다.

다음 다이어그램은 캘린더, 일정, 기타 관련 요소 간의 개념적 관계를 보여줍니다.

기본 캘린더 및 기타 캘린더

기본 캘린더는 단일 사용자 계정과 연결된 특별한 유형의 캘린더입니다. 이 캘린더는 각 신규 사용자 계정에 대해 자동으로 생성되며 ID는 일반적으로 사용자의 기본 이메일 주소와 일치합니다. 계정이 존재하는 한 기본 캘린더는 삭제되거나 사용자가 '소유하지 않는' 상태가 될 수 없습니다. 하지만 다른 사용자와 공유할 수는 있습니다.

기본 캘린더 외에도 다른 캘린더를 원하는 만큼 명시적으로 만들 수 있습니다. 이러한 캘린더는 수정, 삭제, 다른 사용자와 공유가 가능합니다. 이러한 캘린더에는 캘린더를 삭제할 수 있는 독점적 권한을 포함하여 가장 높은 권한을 가진 단일 데이터 소유자가 있습니다. 데이터 소유자의 액세스 수준은 다운그레이드할 수 없습니다. 데이터 소유자는 처음에 캘린더를 만든 사용자로 결정되지만 Google Calendar UI에서 데이터 소유권을 이전할 수 있습니다.

중요: 캘린더를 만들 때는 앱이 캘린더의 의도된 데이터 소유자로 인증하는 것이 좋습니다. 도메인 전체 권한 위임을 사용하여 애플리케이션이 특정 사용자를 대신하여 작업을 수행하도록 허용할 수 있습니다. 인증에 서비스 계정을 사용하지 마세요. 인증에 서비스 계정을 사용하면 서비스 계정이 데이터 소유자가 되어 예기치 않은 동작이 발생할 수 있습니다. 예를 들어 서비스 계정이 데이터 소유자인 경우 데이터 소유권을 이전할 수 없습니다.

캘린더 및 캘린더 목록

Calendars 컬렉션 은 모든 기존 캘린더를 나타냅니다. 이 컬렉션을 사용하여 캘린더를 만들고 삭제할 수 있습니다. 캘린더에 액세스할 수 있는 모든 사용자와 공유되는 전역 속성을 가져오거나 설정할 수도 있습니다. 예를 들어 캘린더의 제목과 기본 시간대는 전역 속성입니다.

CalendarList는 사용자가 목록에 추가한 모든 캘린더 항목의 모음입니다 (웹 UI의 왼쪽 패널에 표시됨). 이 컬렉션을 사용하여 기존 캘린더를 사용자 목록에 추가하거나 사용자 목록에서 삭제할 수 있습니다. 또한 기본 리마인더와 같은 사용자별 캘린더 속성의 값을 가져오고 설정하는 데 사용됩니다. 다른 예는 전경색입니다. 사용자가 동일한 캘린더에 대해 서로 다른 색상을 설정할 수 있기 때문입니다.

참고: 캘린더의 데이터 소유자는 캘린더 목록에서 이 캘린더를 삭제할 수 없습니다.

다음 표에서는 두 컬렉션의 작업 의미를 비교합니다.

작업	Calendars	CalendarList
insert	새 보조 캘린더를 만듭니다. 이 캘린더는 작성자의 캘린더 목록에도 추가되며 캘린더가 삭제되거나 이전되지 않는 한 삭제할 수 없습니다.	기존 캘린더를 사용자 목록에 삽입합니다.
delete	보조 캘린더를 삭제합니다.	사용자 목록에서 캘린더를 삭제합니다.
get	캘린더 메타데이터(예: 제목, 시간대)를 가져옵니다.	메타데이터 및 사용자별 맞춤설정(예: 색상 또는 리마인더 재정의)을 가져옵니다.
patch/update	캘린더 메타데이터를 수정합니다.	사용자별 캘린더 속성을 수정합니다.

반복 일정

일부 일정은 주간 회의, 생일, 공휴일과 같이 정기적으로 여러 번 발생합니다. 시작 시간과 종료 시간이 다른 것 외에는 이러한 반복 일정이 동일한 경우가 많습니다.

일정은 정의된 일정에 따라 반복되는 경우 반복 일정이라고 합니다. 단일 일정은 반복되지 않으며 한 번만 발생합니다.

반복 규칙

반복 일정의 일정은 다음 두 부분으로 정의됩니다.

• 시작 및 종료 필드 (마치 독립형 단일 일정인 것처럼 첫 번째 발생을 정의함) 및

• 반복 필드 (시간이 지남에 따라 일정이 반복되는 방식을 정의함)

반복 필드에는 RRULE 또는 RDATE 또는 EXDATE 속성을 나타내는 문자열 배열이 포함되어 있습니다. RFC 5545에 정의된 대로

RRULE 속성은 일정을 반복하는 정규 규칙을 정의하므로 가장 중요합니다. 이 속성은 여러 구성요소로 구성됩니다. 일부 구성요소는 다음과 같습니다.

• FREQ — 일정이 반복되는 빈도 (예: DAILY 또는 WEEKLY). 필수.

• INTERVAL — FREQ와 함께 작동하여 일정이 반복되는 빈도를 지정합니다. 예를 들어 FREQ=DAILY;INTERVAL=2는 이틀에 한 번을 의미합니다.

• COUNT — 이 일정이 반복되는 횟수입니다.

  COUNT 또는 UNTIL을 사용하여 일정 반복의 종료를 지정할 수 있습니다. 동일한 규칙에서 둘 다 사용하지 마세요.

• UNTIL — 일정이 반복되는 날짜 또는 날짜/시간 (포함).

• BYDAY — 일정이 반복되는 요일 (SU, MO, TU 등). 다른 유사한 구성요소로는 BYMONTH, BYYEARDAY, BYHOUR가 있습니다.

RDATE 속성은 일정 발생이 발생해야 하는 추가 날짜 또는 날짜/시간을 지정합니다. 예를 들어 RDATE;VALUE=DATE:19970101,19970120입니다. 이 속성을 사용하여 RRULE에 포함되지 않은 추가 발생을 추가합니다.

EXDATE 속성은 RDATE와 유사하지만 일정이 발생하지 않아야 하는 날짜 또는 날짜/시간을 지정합니다. 즉, 이러한 발생은 제외되어야 합니다. 이 속성은 반복 규칙에 의해 생성된 유효한 인스턴스를 가리켜야 합니다.

EXDATE 및 RDATE에는 시간대가 있을 수 있으며 종일 일정의 경우 날짜 (날짜/시간 아님)여야 합니다.

각 속성은 반복 필드 내에서 여러 번 발생할 수 있습니다. 반복은 모든 RRULE 및 RDATE 규칙의 합집합에서 모든 EXDATE 규칙에 의해 제외된 규칙을 뺀 것으로 정의됩니다.

다음은 반복 일정의 몇 가지 예입니다.

1. 2015년 9월 15일부터 시작하여 9월 29일에 5번째 발생 후 중지되는 매주 화요일과 금요일 오전 6시부터 오전 7시까지 발생하는 일정:

   ...
   "start": {
    "dateTime": "2015-09-15T06:00:00+02:00",
    "timeZone": "Europe/Zurich"
   },
   "end": {
    "dateTime": "2015-09-15T07:00:00+02:00",
    "timeZone": "Europe/Zurich"
   },
   "recurrence": [
    "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
   ],
   …
   

2. 2015년 6월 1일에 시작하여 6월 10일을 제외하고 6월 9일과 11일을 포함하여 한 달 내내 3일마다 반복되는 종일 일정:

   ...
   "start": {
    "date": "2015-06-01"
   },
   "end": {
    "date": "2015-06-02"
   },
   "recurrence": [
    "EXDATE;VALUE=DATE:20150610",
    "RDATE;VALUE=DATE:20150609,20150611",
    "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
   ],
   …
   

인스턴스 및 예외

반복 일정은 여러 인스턴스(서로 다른 시간에 발생하는 특정 발생) 로 구성됩니다. 이러한 인스턴스는 일정 자체로 작동합니다.

반복 일정 수정은 전체 반복 일정 (및 모든 인스턴스)에 영향을 미치거나 개별 인스턴스에만 영향을 미칠 수 있습니다. 상위 반복 일정과 다른 인스턴스를 예외 라고 합니다.

예를 들어 예외에는 다른 요약, 다른 시작 시간 또는 해당 인스턴스에만 초대된 추가 참석자가 있을 수 있습니다. 반복 일정을 삭제하지 않고 인스턴스를 완전히 취소할 수도 있습니다 (인스턴스 취소는 일정 status에 반영됨).

Google Calendar API를 통해 반복 일정 및 인스턴스를 사용하는 방법의 예는 여기에서확인할 수 있습니다.

시간대

시간대는 균일한 표준 시간을 준수하는 지역을 지정합니다. Google Calendar API에서는 IANA 시간대 식별자를 사용하여 시간대를 지정합니다.

캘린더와 일정 모두에 시간대를 설정할 수 있습니다. 다음 섹션에서는 이러한 설정의 영향을 설명합니다.

캘린더 시간대

캘린더 시간대는 쿼리 결과에 미치는 영향으로 인해 기본 시간대 라고도 합니다. 캘린더 시간대는 시간 값을 events.get(), events.list(), 및 events.instances() 메서드에서 해석하거나 표시하는 방식에 영향을 미칩니다.

쿼리 결과 시간대 변환

get(), list(), instances() 메서드의 결과는 timeZone 매개변수에 지정한 시간대로 반환됩니다. 이 매개변수를 생략하면 이러한 메서드는 모두 캘린더 시간대를 기본값으로 사용합니다.

시간 범위 쿼리와 종일 일정 일치

The list() 및 instances() 메서드를 사용하면 시작 시간 및 종료 시간 필터를 지정할 수 있으며 메서드는 지정된 범위에 속하는 인스턴스를 반환합니다. 캘린더 시간대는 종일 일정의 시작 시간과 종료 시간을 계산하여 필터 사양에 속하는지 확인하는 데 사용됩니다.

일정 시간대

일정 인스턴스에는 시작 시간과 종료 시간이 있으며 이러한 시간의 사양에는 시간대가 포함될 수 있습니다. 시간대는 여러 가지 방법으로 지정할 수 있습니다. 다음은 모두 동일한 시간을 지정합니다.

• dateTime 필드에 시간대 오프셋을 포함합니다(예: 2017-01-25T09:00:00-0500).
• 오프셋 없이 시간을 지정합니다(예: 2017-01-25T09:00:00). timeZone 필드를 비워 둡니다(기본 시간대가 암시적으로 사용됨).
• 오프셋 없이 시간을 지정합니다(예: 2017-01-25T09:00:00). 하지만 timeZone 필드를 사용하여 시간대를 지정합니다.

원하는 경우 UTC로 일정 시간을 지정할 수도 있습니다.

• UTC로 시간을 지정합니다. 2017-01-25T14:00:00Z 또는 0 오프셋 2017-01-25T14:00:00+0000을 사용합니다.

이러한 모든 경우에 일정 시간의 내부 표현은 동일하지만 timeZone 필드를 설정하면 Calendar UI를 사용하여 일정 시간대를 설정할 때와 마찬가지로 일정에 시간대가 연결됩니다.

단일 일정의 경우 일정의 시작 시간과 종료 시간에 서로 다른 시간대를 지정할 수 있습니다. (이렇게 하면 실제로 서로 다른 시간대에서 시작하고 종료되는 여행과 같은 일정에 도움이 될 수 있습니다.) 반복 일정은 아래를 참고하세요.

반복 일정 시간대

반복 일정의 경우 항상 단일 시간대를 지정해야 합니다. 일정의 반복을 확장하려면 시간대가 필요합니다.