Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Labels

Auf dieser Seite wird erläutert, was Labels sind, wie sie in Kalendern verwaltet werden und wie Sie sie mit der Google Calendar API Terminen zuweisen können.

In Google Kalender können Sie das Erscheinungsbild Ihrer Termine anpassen, indem Sie ihnen benutzerdefinierte Farben und Namen zuweisen. Bisher waren Termine auf eine feste Anzahl indexbasierter Farben (colorId) beschränkt. Mit Labels können Sie eine flexible, benutzerdefinierte Palette pro Kalender definieren und diese Labels direkt auf Termine anwenden.

Diese Funktion ersetzt das alte indexbasierte Feld colorId. Wenn Sie Labels verwenden möchten, müssen Sie in Ihren API-Anfragen den Parameter eventLabelVersion=1 angeben. Wenn dieser Parameter festgelegt ist, wird das alte Feld colorId ignoriert.

Labels in einem Kalender verwalten

Mit der Eigenschaft labelProperties der Ressource „Calendars“ können Sie bis zu 200 benutzerdefinierte Labels pro Kalender definieren.

Verwenden Sie die Calendars.insert oder Calendars.update Methoden, um Labels zu verwalten. Für jedes Label sind eine id, eine backgroundColor im Hexadezimalformat und optional ein name erforderlich.

Hinweis:Sie benötigen owner-Zugriff auf einen Kalender, um seine Labels zu definieren oder zu ändern.

Darstellung der Kalenderressource

{
  "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"
      }
    ]
  }
}

Beispiel: Labels in einem Kalender hinzufügen und entfernen

Wenn Sie Labels hinzufügen oder entfernen möchten, sollten Sie zuerst den Kalender lesen, um die aktuelle Liste der Labels abzurufen. Ändern Sie die Liste in Ihrem Code und aktualisieren Sie dann den Kalender mit der aktualisierten Liste, um zu vermeiden, dass andere Labels überschrieben werden.

In den folgenden Beispielen wird gezeigt, wie Sie einen Kalender abrufen, ein Label mit der ID 11111111-2222-3333-4444-555555555555 entfernen, zwei neue Labels (22222222-3333-4444-5555-666666666666 und 33333333-4444-5555-6666-777777777777) hinzufügen und den Kalender aktualisieren:

Ok

// 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

Im folgenden HTTP-Rohbeispiel sehen Sie die endgültige PUT-Anfrage zum Aktualisieren des Kalenders mit der neuen Liste von Labels. Achten Sie darauf, dass Sie diese zuerst mit allen vorhandenen Labels zusammengeführt haben.

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"
      }
    ]
  }
}

Terminen Labels zuweisen

Sobald Labels im Kalender definiert sind, können Sie sie einzelnen Terminen zuweisen, indem Sie die eventLabelId Eigenschaft für die Ressource „Events“ festlegen.

Sie können diese Eigenschaft festlegen oder ändern, wenn Sie die Methoden insert, update oder patch aufrufen.

Hinweis: Sie benötigen mindestens writerWithoutPrivateAccess-Zugriff (oder höher: writer oder owner) auf einen Kalender, um seinen Terminen Labels zuzuweisen.

Hinweis:Sie müssen ?eventLabelVersion=1 an die Anfrage-URL anhängen, um dieses Feld zu verarbeiten.

Darstellung der Ereignisressource

{
  "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"
}

Beispiel: Termin mit einem Label erstellen

In den folgenden Beispielen wird gezeigt, wie Sie einen Termin mit einem benutzerdefinierten Label erstellen:

Ok

// 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"
}

Wenn Sie ein vorhandenes Label aus einem Termin entfernen möchten, legen Sie eventLabelId auf einen leeren String ("") fest oder lassen Sie das Feld in einer update Anfrage ganz weg.

Labels Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Labels in einem Kalender verwalten

Darstellung der Kalenderressource

Beispiel: Labels in einem Kalender hinzufügen und entfernen

Ok

Java

JavaScript

Python

HTTP

Terminen Labels zuweisen

Darstellung der Ereignisressource

Beispiel: Termin mit einem Label erstellen

Ok

Java

JavaScript

Python

HTTP

Labels