캘린더 및 일정

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 가이드에서는 캘린더, 일정, 이러한 항목 간의 관계를 설명합니다.

캘린더

캘린더는 요약, 기본 시간대, 위치 등의 추가 메타데이터와 함께 관련 이벤트의 모음입니다. 각 캘린더는 이메일 주소인 ID로 식별됩니다. 캘린더에 소유자가 여러 명 있을 수 있습니다.

이벤트

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

이벤트 유형

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

  • 단일 이벤트는 고유한 발생을 나타냅니다.
  • 반복 이벤트는 여러 번 일치하는 항목을 정의합니다.

시간 지정 또는 종일로 설정할 수도 있습니다.

  • 시간 지정 이벤트는 두 특정 시점 사이에 발생합니다. 시간이 지정된 이벤트는 start.dateTimeend.dateTime 필드를 사용하여 발생 시점을 지정합니다.
  • 종일 이벤트는 종일 또는 연속된 며칠에 걸쳐 진행됩니다. 종일 이벤트는 start.dateend.date 필드를 사용하여 발생 시점을 지정합니다. 종일 일정에는 시간대 필드가 중요하지 않습니다.

주최자

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

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

기본 캘린더 및 기타 캘린더

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

기본 캘린더 외에도 얼마든지 다른 캘린더를 만들 수 있습니다. 이러한 캘린더는 여러 사용자 간에 수정, 삭제, 공유할 수 있습니다.

캘린더 및 캘린더 목록

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

CalendarList는 웹 UI의 왼쪽 패널에 표시된 대로 사용자가 목록에 추가한 모든 캘린더 항목의 모음입니다. 사용자 목록에 기존 캘린더를 추가하거나 삭제하는 데 사용할 수 있습니다. 또한 기본 알림과 같은 사용자별 캘린더 속성의 값을 검색하고 설정하는 데도 사용할 수 있습니다. 또 다른 예는 포그라운드 색상입니다. 사용자마다 동일한 캘린더에 다양한 색상을 설정할 수 있기 때문입니다.

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

작업 캘린더 캘린더 목록
insert 새 보조 캘린더를 만듭니다. 기본적으로 이 캘린더는 작성자의 캘린더 목록에도 추가됩니다. 기존 캘린더를 사용자 목록에 삽입합니다.
delete 보조 캘린더를 삭제합니다. 사용자 목록에서 캘린더를 삭제합니다.
get 캘린더 메타데이터(예: 제목, 시간대)를 검색합니다. 메타데이터 색상별 재정의 알림과 재정의 알림을 검색합니다.
patch/update 캘린더 메타데이터를 수정합니다. 사용자별 캘린더 속성을 수정합니다.

반복 일정

주간 회의, 생일, 공휴일 등 일부 이벤트는 정기적인 일정에 따라 여러 번 발생합니다. 시작 시간과 종료 시간이 다른 경우를 제외하고 이러한 반복 이벤트는 동일한 경우가 많습니다.

정의된 일정에 따라 반복되면 이벤트를 반복이라고 합니다. 단일 이벤트는 반복되지 않으며 한 번만 발생합니다.

반복 규칙

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

  • 시작 필드 및 종료 필드 (독립형 단일 이벤트인 것처럼 첫 번째 어커런스 정의)

  • 반복 필드 (일정의 반복 방식 정의)입니다.

recurrence 필드에는 RFC 5545에 정의된 대로 하나 이상의 RRULE, RDATE 또는 EXDATE 속성을 나타내는 문자열 배열이 포함됩니다.

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

  • FREQ - 이벤트를 반복해야 하는 빈도 (예: DAILY 또는 WEEKLY). 필수사항

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

  • COUNT: 이 일정을 반복해야 하는 횟수입니다.

  • UNTIL: 이벤트를 반복해야 하는 날짜 또는 날짜-시간 (포함)입니다.

  • BYDAY: 이벤트를 반복할 요일 (SU, MO, TU 등)입니다. 다른 유사한 구성요소에는 BYMONTH, BYYEARDAY, BYHOUR이 있습니다.

RDATE 속성은 이벤트 발생이 예상되는 추가 날짜 또는 날짜-시간을 지정합니다. 예를 들면 RDATE;VALUE=DATE:19970101,19970120입니다. 이를 사용하여 RRULE에서 다루지 않는 추가 어커런스를 추가합니다.

EXDATE 속성은 RDATE와 비슷하지만 이벤트가 발생하지 않아야 하는 날짜나 날짜-시간을 지정합니다. 즉, 이러한 어커런스는 제외해야 합니다. 이는 반복 규칙에서 생성된 유효한 인스턴스를 가리켜야 합니다.

EXDATERDATE는 시간대를 가질 수 있으며 종일 이벤트의 날짜 (날짜-시간 아님)여야 합니다.

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

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

  1. 2015년 9월 15일부터 9월 29일의 다섯 번째 발생 이후 화요일과 금요일 오전 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일에 시작하여 3월마다 6일마다 반복되는 종일 일정(6월 10일 제외, 6월 9일 및 11일 제외):

    ...
    "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 이벤트에 반영됨).

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

시간대

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

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

캘린더 시간대

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

쿼리 결과 시간대 변환
get(), list(), instances() 메서드의 결과는 timeZone 매개변수에서 지정한 시간대로 반환됩니다. 이 매개변수를 생략하면 이러한 메서드는 모두 캘린더 시간대를 기본값으로 사용합니다.
종일 이벤트를 시간 괄호로 묶인 쿼리에 일치시키기
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 오프셋 2017-01-25T14:00:00+0000을 사용하세요.

이벤트 시간의 내부 표현은 모든 경우에서 동일하지만, timeZone 필드를 설정하면 캘린더 UI를 사용하여 이벤트 시간대를 설정할 때처럼 일정에 시간대를 연결할 수 있습니다.

이벤트의 시간대를 보여주는 스크린샷 프래그먼트

반복 일정 시간대

반복 이벤트의 경우 항상 단일 시간대를 지정해야 합니다. 이벤트의 반복을 확장하기 위해 필요합니다.