Calendar API로 일정을 조회, 생성, 수정, 삭제하고, 캘린더를 관리할 수 있다.
Calendar API를 호출하려면 구성원 계정 또는 서비스 계정으로 인증하여 얻은 Access Token이 필요하다.
API scope는 calendar, calendar.read이다.
캘린더에는 모든 사용자가 가진 '기본 캘린더', 선택적으로 추가 및 삭제할 수 있는 '캘린더', 조직 및 그룹이 있는 '조직/그룹 캘린더'가 있다.
이 중 '캘린더'는 다음 API로 만들 수 있다.
| HTTP Request | Description |
|---|---|
| POST /calendars | 캘린더 생성 |
사용자가 액세스할 수 있는 캘린더 목록은 다음 API로 얻을 수 있다.
| HTTP Request | Description |
|---|---|
| GET/users/{userId}/calendar | 기본 캘린더 공유 속성 조회 |
| GET /users/{userId}/calendar-personals | 캘린더 개인 속성 목록 조회 |
PC 혹은 모바일 앱에서 캘린더 목록에 표시 여부와 캘린더의 순서를 설정할 수 있다.
| HTTP Request | Description |
|---|---|
| PATCH /users/{userId}/calendar-personals/{calendarId} | 캘린더 개인 속성 수정 |
캘린더 일정은 다음 API로 관리한다. API를 사용할 때 calendarId를 지정해야 한다.
기본 캘린더는 다음 API로 일정을 관리할 수 있다. 이 API들은 calendarId를 지정하지 않고 사용한다.
| HTTP Request | Description |
|---|---|
| POST /users/{userId}/calendar/events | 기본 캘린더 일정 생성 |
| GET /users/{userId}/calendar/events | 기본 캘린더 일정 목록 조회 |
| GET /users/{userId}/calendar/events/{eventId} | 기본 캘린더 일정 조회 |
| PUT /users/{userId}/calendar/events/{eventId} | 기본 캘린더 일정 수정 |
| DELETE /users/{userId}/calendar/events/{eventId} | 기본 캘린더 일정 삭제 |
일정은 eventComponents 객체로 요청하거나 응답받는다.
다음은 eventComponents 객체의 예시다.
{ "eventComponents": [ { "eventId": "EventID1234567890abcdefghijk", "summary": "일정 예시", "start": { "dateTime": "2023-05-14T08:00:00", "timeZone": "Asia/Seoul" }, "end": { "dateTime": "2023-05-14T09:00:00", "timeZone": "Asia/Seoul" }, "description" : "테스트 일정입니다.", "location" : "중앙 회의실", "transparency": "OPAQUE" } ]}위 예시는 일정의 내용(summary), 일정 시작 시간과 종료 시간(dateTime), 각각의 시간대(timeZone), 메모(description)와 장소(location), 바쁨/한가함 상태(transparency)를 포함한다.
일정 생성 시 지정한 eventId는 고유한 값으로 다른 일정의 값과 겹치지 않는다. eventId를 지정하지 않으면 자동으로 eventId가 할당된다.
일정의 주최자는 organizer로, 참가자는 attendees로 지정한다. 둘 다 이메일 주소(email)는 필수이며 이름(displayName)은 선택적으로 지정한다.
{ "eventComponents": [ { "eventId": "EventID1234567890abcdefghijk", "summary": "일정 예시", "start": { "dateTime": "2023-05-14T08:00:00", "timeZone": "Asia/Seoul" }, "end": { "dateTime": "2023-05-14T09:00:00", "timeZone": "Asia/Seoul" }, "description" : "테스트 일정입니다.", "location" : "중앙 회의실", "organizer": { "email" : "organizer@example.com", "displayName" : "회의 주최자" }, "attendees" : [ { "email" : "attendee@example.com", "displayName" : "회의 참가자", "partstat" : "ACCEPTED", "isOptional" : true } ] } ]}설비를 지정하려면 isResource 속성을 true로 입력하고 설비 ID(id)와 리소스 고윳값(resourceValue)을 지정한다.id와 resourceValue는 설비에 할당된 값이다. resourceValue는 응답을 통해 확인할 수 있다.
... "attendees": [ { "id": "12345678/12345678@97d9ddb4-ae93-4469-8471-123456781234", "resourceValue": "https://calendar.worksmobile.com/resources/resource/12345678/12345678@97d9ddb4-ae93-4469-8471-123456781234", "isResource": true } ]...eventComponents 객체는 eventId가 같은 하나 또는 여러 개의 Event 객체를 포함한다.eventComponents 객체가 하나의 Event 객체를 포함하면 일회성의 일정이거나 예외가 없는 반복 일정이다. 반복 정보는 recurrence 배열로 표현되며 recurrence 배열이 없으면 일회성의 일정이다.eventComponents 객체가 여러 개의 Event를 포함하면 예외가 있는 반복 일정이다.
다음은 예외를 포함한 eventComponts 객체의 예시다.
{ "eventComponents": [ { "eventId": "EventID1234567890abcdefg", "summary": "반복 일정 예시", "start": { "dateTime": "2023-05-24T08:00:00", "timeZone": "Asia/Seoul" }, "end": { "dateTime": "2023-05-24T09:00:00", "timeZone": "Asia/Seoul" }, "recurrence": [ "RRULE:FREQ=DAILY;UNTIL=20230525T230000Z;INTERVAL=1", "EXDATE;TZID=Asia/Seoul:20230525T080000" ] }, { "eventId": "EventID1234567890abcdefg", "summary": "예외 일정", "start": { "dateTime": "2023-05-25T08:30:00", "timeZone": "Asia/Seoul" }, "end": { "dateTime": "2023-05-25T09:30:00", "timeZone": "Asia/Seoul" }, "recurringEventId": "TZID=Asia/Seoul:20230525T080000" } ]}첫 번째 Event 객체는 서울 시간으로 2023-05-24T08:00:00부터 2023-05-24T09:00:00까지 반복되는 반복 일정 예시를 나타내고 있다. recurrence 속성이 있으므로 반복 일정임을 알 수 있다. 반복 정보는 RRULE로 표시된다.
위 예시에서 INTEREVAL은 1, FREQ는 DAILY이므로 20230525T230000Z까지 매일 반복되는 일정인 것을 알 수 있다. 20230525T230000Z는 UTC이므로 서울 시간으로는 1월 26일 8시 일정이 마지막 일정인 것을 의미한다.EXDATE는 반복 예외 일정을 나타내는 ID로 TZID=Asia/Seoul:20230525T080000에 해당한다.
두 번째 Event 객체에서는 예외 일정의 내용을 확인할 수 있다. recurringEventId는 반복 일정의 recurrence 객체에 포함되는 EXDATE의 값 TZID=Asia/Seoul:20230525T080000과 일치한다. 해당 객체에서 일정의 내용과 일정의 시작·종료 시간이 반복 일정과 다름을 확인할 수 있다.