בדף הזה מוסבר מהן תוויות, איך מנהלים אותן ביומנים ואיך אפשר להקצות אותן לאירועים באמצעות Google Calendar API.
אתם יכולים להתאים אישית את המראה של האירועים ביומן Google, על ידי הקצאת צבעים ושמות בהתאמה אישית. בעבר, הצבעים של האירועים היו מוגבלים לקבוצה קבועה של צבעים מבוססי-אינדקס (colorId). עם תוויות, אתם יכולים להגדיר פלטה גמישה בהתאמה אישית לכל יומן ולהחיל את התוויות האלה ישירות על האירועים.
ניהול תוויות ביומן
אפשר להגדיר עד 200 תוויות מותאמות אישית לכל יומן באמצעות המאפיין labelProperties במשאב Calendars.
כדי לנהל את התוויות, משתמשים בשיטות Calendars.insert או Calendars.update. לכל תווית צריך להיות id, 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"
}
]
}
}
דוגמה: הוספה והסרה של תוויות ביומן
כדי להוסיף או להסיר תוויות, קודם צריך לקרוא את היומן כדי לקבל את רשימת התוויות הנוכחית, לשנות את הרשימה בקוד ואז לעדכן את היומן עם הרשימה המעודכנת כדי למנוע החלפה של תוויות אחרות.
בדוגמאות הבאות מוצגות פעולות לאחזור יומן, להסרת תווית עם המזהה 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)
Java
// 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());
JavaScript
// 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"
}
]
}
}
הקצאת תוויות לאירועים
אחרי שמגדירים את התוויות ביומן, אפשר להקצות אותן לאירועים ספציפיים על ידי הגדרת המאפיין eventLabelId במשאב Events.
אפשר להגדיר או לשנות את המאפיין הזה כשקוראים לשיטות insert, update או patch.
ייצוג של משאב מסוג Event
{
"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)
Java
// 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());
JavaScript
// 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.