Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Etykiety

Na tej stronie znajdziesz informacje o etykietach, sposobie zarządzania nimi w kalendarzach oraz o tym, jak przypisywać je do wydarzeń za pomocą interfejsu Google Calendar API.

Kalendarz Google umożliwia dostosowywanie wyglądu wydarzeń przez przypisywanie im spersonalizowanych kolorów i nazw. Wcześniej wydarzenia były ograniczone do stałego zestawu kolorów opartych na indeksach (colorId). Dzięki etykietom możesz zdefiniować elastyczną, niestandardową paletę dla każdego kalendarza i stosować te etykiety bezpośrednio do wydarzeń.

Ta funkcja zastępuje starsze pole colorId oparte na indeksie. Aby używać etykiet, musisz określić parametr eventLabelVersion=1 w żądaniach interfejsu API. Gdy ten parametr jest ustawiony, starsze pole colorId jest ignorowane.

Zarządzanie etykietami w kalendarzu

W przypadku każdego kalendarza możesz zdefiniować maksymalnie 200 etykiet niestandardowych za pomocą właściwości labelProperties w zasobie Calendars.

Aby zarządzać etykietami, użyj metody Calendars.insert lub Calendars.update. Każda etykieta wymaga id, backgroundColor w formacie szesnastkowym i opcjonalnego name.

Uwaga: aby zdefiniować lub zmodyfikować etykiety kalendarza, musisz mieć do niego dostęp na poziomie owner.

Prezentacja zasobu kalendarza

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

Przykład: dodawanie i usuwanie etykiet w kalendarzu

Aby dodać lub usunąć etykiety, najpierw odczytaj kalendarz, aby uzyskać bieżącą listę etykiet, zmodyfikuj listę w kodzie, a następnie zaktualizuj kalendarz za pomocą zaktualizowanej listy, aby uniknąć zastąpienia innych etykiet.

Poniższe przykłady pokazują, jak pobrać kalendarz, usunąć etykietę o identyfikatorze 11111111-2222-3333-4444-555555555555, dodać 2 nowe etykiety (22222222-3333-4444-5555-666666666666 i 33333333-4444-5555-6666-777777777777) oraz zaktualizować kalendarz:

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

Poniższy przykład surowego żądania HTTP pokazuje końcowe żądanie PUT, które aktualizuje kalendarz o nową listę etykiet. Najpierw połącz je z dotychczasowymi etykietami.

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

Przypisywanie etykiet do wydarzeń

Po zdefiniowaniu etykiet w kalendarzu możesz przypisać je do poszczególnych wydarzeń, ustawiając właściwość eventLabelId w zasobie Events.

Tę właściwość możesz ustawić lub zmienić podczas wywoływania metod insert, update lub patch.

Uwaga: aby przypisywać etykiety do wydarzeń w kalendarzu, musisz mieć do niego co najmniej dostęp writerWithoutPrivateAccess (lub wyższy: writer lub owner).

Pamiętaj: aby przetworzyć to pole, musisz dodać do adresu URL żądania znak ?eventLabelVersion=1.

Prezentacja zasobu zdarzenia

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

Przykład: tworzenie wydarzenia z etykietą

Przykłady poniżej pokazują, jak utworzyć zdarzenie z etykietą niestandardową:

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

Aby usunąć z wydarzenia istniejącą etykietę, ustaw wartość eventLabelId na pusty ciąg znaków ("") lub całkowicie pomiń to pole w żądaniu update.

Etykiety Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Zarządzanie etykietami w kalendarzu

Prezentacja zasobu kalendarza

Przykład: dodawanie i usuwanie etykiet w kalendarzu

Go

Java

JavaScript

Python

HTTP

Przypisywanie etykiet do wydarzeń

Prezentacja zasobu zdarzenia

Przykład: tworzenie wydarzenia z etykietą

Go

Java

JavaScript

Python

HTTP

Etykiety