이 페이지에서는 라벨이 무엇인지, 캘린더에서 라벨이 관리되는 방식, Google Calendar API를 사용하여 이벤트에 라벨을 할당하는 방법을 설명합니다.
Google Calendar에서는 사용자 지정 색상과 이름을 할당하여 일정의 모양을 맞춤설정할 수 있습니다. 이전에는 이벤트가 고정된 색인 기반 색상 (colorId)으로 제한되었습니다. 라벨을 사용하면 캘린더별로 유연한 맞춤 팔레트를 정의하고 이러한 라벨을 이벤트에 직접 적용할 수 있습니다.
캘린더의 라벨 관리
Calendars 리소스의 labelProperties 속성을 사용하여 캘린더당 최대 200개의 맞춤 라벨을 정의할 수 있습니다.
라벨을 관리하려면 Calendars.insert 또는 Calendars.update 메서드를 사용합니다. 각 라벨에는 id, 16진수 형식의 backgroundColor, 선택사항인 name가 필요합니다.
캘린더 리소스 표현
{
"kind": "calendar#calendar",
"id": "primary",
"summary": "My Team Calendar",
"labelProperties": {
"eventLabels": [
{
"id": "42617328-8756-4291-8273-192837465647",
"backgroundColor": "#039be5",
"name": "Important Project"
},
{
"id": "19283746-9182-4736-8271-918273645261",
"backgroundColor": "#33b679",
"name": "Team Meeting"
}
]
}
}
예: 캘린더에서 라벨 추가 및 삭제
라벨을 추가하거나 삭제하려면 먼저 캘린더를 읽어 현재 라벨 목록을 가져오고, 코드에서 목록을 수정하고, 업데이트된 목록으로 캘린더를 업데이트하여 다른 라벨을 덮어쓰지 않도록 해야 합니다.
다음 샘플은 캘린더를 가져오고, ID가 11111111-2222-3333-4444-555555555555인 라벨을 삭제하고, 새 라벨 (22222222-3333-4444-5555-666666666666 및 33333333-4444-5555-6666-777777777777)을 두 개 추가하고, 캘린더를 업데이트하는 방법을 보여줍니다.
Go
// Refer to the Go quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/go
// 1. Read the calendar to get existing labels
calendar, err := srv.Calendars.Get("primary").Do()
if err != nil {
log.Fatalf("Unable to retrieve calendar: %v", err)
}
if calendar.LabelProperties == nil {
calendar.LabelProperties = &calendar.LabelProperties{}
}
labels := calendar.LabelProperties.EventLabels
// 2. Remove a label with a specific ID (UUID format)
targetIdToRemove := "11111111-2222-3333-4444-555555555555"
var updatedLabels []*calendar.EventLabel
for _, label := range labels {
if label.Id != targetIdToRemove {
updatedLabels = append(updatedLabels, label)
}
}
labels = updatedLabels
// 3. Add 2 new labels with UUID IDs
labels = append(labels, &calendar.EventLabel{
Id: "22222222-3333-4444-5555-666666666666",
BackgroundColor: "#8e24aa",
Name: "Design Work",
})
labels = append(labels, &calendar.EventLabel{
Id: "33333333-4444-5555-6666-777777777777",
BackgroundColor: "#f4511e",
Name: "Urgent Review",
})
// 4. Update the calendar with the new list
calendar.LabelProperties.EventLabels = labels
updatedCalendar, err := srv.Calendars.Update("primary", calendar).Do()
if err != nil {
log.Fatalf("Unable to update calendar: %v", err)
}
fmt.Printf("Calendar updated: %s\n", updatedCalendar.Summary)
자바
// Refer to the Java quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/java
// 1. Read the calendar to get existing labels
Calendar calendar = service.calendars().get("primary").execute();
LabelProperties labelProperties = calendar.getLabelProperties();
if (labelProperties == null) {
labelProperties = new LabelProperties();
}
List<EventLabel> labels = labelProperties.getEventLabels();
if (labels == null) {
labels = new ArrayList<>();
} else {
// Create a mutable copy since the returned list might be immutable
labels = new ArrayList<>(labels);
}
// 2. Remove a label with a specific ID (UUID format)
String targetIdToRemove = "11111111-2222-3333-4444-555555555555";
labels.removeIf(label -> targetIdToRemove.equals(label.getId()));
// 3. Add 2 new labels with UUID IDs
labels.add(new EventLabel()
.setId("22222222-3333-4444-5555-666666666666")
.setBackgroundColor("#8e24aa")
.setName("Design Work"));
labels.add(new EventLabel()
.setId("33333333-4444-5555-6666-777777777777")
.setBackgroundColor("#f4511e")
.setName("Urgent Review"));
// 4. Update the calendar with the new list
labelProperties.setEventLabels(labels);
calendar.setLabelProperties(labelProperties);
Calendar updatedCalendar = service.calendars().update("primary", calendar)
.execute();
System.out.printf("Calendar updated: %s\n", updatedCalendar.getSummary());
자바스크립트
// Refer to the Node.js quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/nodejs
// 1. Retrieve the calendar resource
calendar.calendars.get({
calendarId: 'primary'
}, (err, res) => {
if (err) return console.log('The API returned an error: ' + err);
// Extract existing labels from the calendar resource
const cal = res.data;
if (!cal.labelProperties) {
cal.labelProperties = {};
}
if (!cal.labelProperties.eventLabels) {
cal.labelProperties.eventLabels = [];
}
// 2. Remove a label with a specific ID (UUID format)
const targetIdToRemove = '11111111-2222-3333-4444-555555555555';
cal.labelProperties.eventLabels = cal.labelProperties.eventLabels.filter(
label => label.id !== targetIdToRemove
);
// 3. Add 2 new labels with UUID IDs
cal.labelProperties.eventLabels.push({
id: '22222222-3333-4444-5555-666666666666',
backgroundColor: '#8e24aa',
name: 'Design Work'
});
cal.labelProperties.eventLabels.push({
id: '33333333-4444-5555-6666-777777777777',
backgroundColor: '#f4511e',
name: 'Urgent Review'
});
// 4. Update the calendar with the new list
calendar.calendars.update({
calendarId: 'primary',
resource: cal
}, (updateErr, updateRes) => {
if (updateErr) return console.log('Update failed: ' + updateErr);
console.log(`Calendar updated: ${updateRes.data.summary}`);
});
});
Python
# Refer to the Python quickstart on how to setup the service:
# https://developers.google.com/workspace/calendar/quickstart/python
# 1. Read the calendar to get existing labels
calendar = service.calendars().get(calendarId='primary').execute()
label_properties = calendar.setdefault('labelProperties', {})
labels = label_properties.setdefault('eventLabels', [])
# 2. Remove a label with a specific ID (UUID format)
target_id_to_remove = "11111111-2222-3333-4444-555555555555"
labels = [l for l in labels if l.get('id') != target_id_to_remove]
# 3. Add 2 new labels with UUID IDs
labels.append({
'id': '22222222-3333-4444-5555-666666666666',
'backgroundColor': '#8e24aa',
'name': 'Design Work'
})
labels.append({
'id': '33333333-4444-5555-6666-777777777777',
'backgroundColor': '#f4511e',
'name': 'Urgent Review'
})
# 4. Update the calendar with the new list
label_properties['eventLabels'] = labels
calendar['labelProperties'] = label_properties
updated_calendar = service.calendars().update(
calendarId='primary',
body=calendar
).execute()
print(f"Calendar updated: {updated_calendar.get('summary')}")
HTTP
다음 원시 HTTP 예시에서는 새 라벨 목록으로 캘린더를 업데이트하는 최종 PUT 요청을 보여줍니다. 먼저 기존 라벨과 병합해야 합니다.
PUT https://www.googleapis.com/calendar/v3/calendars/primary
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/json
{
"summary": "Updated Team Calendar",
"labelProperties": {
"eventLabels": [
{
"id": "22222222-3333-4444-5555-666666666666",
"backgroundColor": "#8e24aa",
"name": "Design Work"
},
{
"id": "33333333-4444-5555-6666-777777777777",
"backgroundColor": "#f4511e",
"name": "Urgent Review"
}
]
}
}
이벤트에 라벨 할당
캘린더에 라벨이 정의되면 Events 리소스에서 eventLabelId 속성을 설정하여 개별 일정에 라벨을 할당할 수 있습니다.
insert, update 또는 patch 메서드를 호출할 때 이 속성을 설정하거나 변경할 수 있습니다.
이벤트 리소스 표현
{
"kind": "calendar#event",
"id": "sample-event-id",
"summary": "Review Design Specs",
"start": {
"dateTime": "2026-07-01T10:00:00Z"
},
"end": {
"dateTime": "2026-07-01T11:00:00Z"
},
"eventLabelId": "22222222-3333-4444-5555-666666666666"
}
예: 라벨이 있는 이벤트 만들기
다음 샘플은 맞춤 라벨이 있는 이벤트를 만드는 방법을 보여줍니다.
Go
// Refer to the Go quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/go
event := &calendar.Event{
Summary: "Design Sync",
Start: &calendar.EventDateTime{
DateTime: "2026-07-02T14:00:00Z",
},
End: &calendar.EventDateTime{
DateTime: "2026-07-02T15:00:00Z",
},
EventLabelId: "22222222-3333-4444-5555-666666666666",
}
createdEvent, err := srv.Events.Insert("primary", event).EventLabelVersion(1).Do()
if err != nil {
log.Fatalf("Unable to create event: %v", err)
}
fmt.Printf("Event created: %s\n", createdEvent.HtmlLink)
자바
// Refer to the Java quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/java
Event event = new Event()
.setSummary("Design Sync")
.setStart(new EventDateTime().setDateTime(new DateTime("2026-07-02T14:00:00Z")))
.setEnd(new EventDateTime().setDateTime(new DateTime("2026-07-02T15:00:00Z")))
.setEventLabelId("22222222-3333-4444-5555-666666666666");
Event createdEvent = service.events().insert("primary", event)
.setEventLabelVersion(1L)
.execute();
System.out.printf("Event created: %s\n", createdEvent.getHtmlLink());
자바스크립트
// Refer to the Node.js quickstart on how to setup the service:
// https://developers.google.com/workspace/calendar/quickstart/nodejs
const event = {
summary: 'Design Sync',
start: {
dateTime: '2026-07-02T14:00:00Z',
},
end: {
dateTime: '2026-07-02T15:00:00Z',
},
eventLabelId: '22222222-3333-4444-5555-666666666666',
};
calendar.events.insert({
calendarId: 'primary',
resource: event,
eventLabelVersion: 1,
}, (err, res) => {
if (err) return console.log('The API returned an error: ' + err);
console.log(`Event created: ${res.data.htmlLink}`);
});
Python
# Refer to the Python quickstart on how to setup the service:
# https://developers.google.com/workspace/calendar/quickstart/python
event = {
'summary': 'Design Sync',
'start': {
'dateTime': '2026-07-02T14:00:00Z',
},
'end': {
'dateTime': '2026-07-02T15:00:00Z',
},
'eventLabelId': '22222222-3333-4444-5555-666666666666'
}
event = service.events().insert(
calendarId='primary',
body=event,
eventLabelVersion=1
).execute()
print(f"Event created: {event.get('htmlLink')}")
HTTP
POST https://www.googleapis.com/calendar/v3/calendars/primary/events?eventLabelVersion=1
Authorization: Bearer [YOUR_ACCESS_TOKEN]
Content-Type: application/json
{
"summary": "Design Sync",
"start": {
"dateTime": "2026-07-02T14:00:00Z"
},
"end": {
"dateTime": "2026-07-02T15:00:00Z"
},
"eventLabelId": "22222222-3333-4444-5555-666666666666"
}
이벤트에서 기존 라벨을 삭제하려면 eventLabelId을 빈 문자열 ("")로 설정하거나 update 요청에서 필드를 완전히 생략하세요.