این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

برچسب ها

این صفحه توضیح می‌دهد که برچسب‌ها چه هستند، چگونه در تقویم‌ها مدیریت می‌شوند و چگونه می‌توانید با استفاده از API تقویم گوگل، آن‌ها را به رویدادها اختصاص دهید.

تقویم گوگل به شما امکان می‌دهد ظاهر رویدادهای خود را با اختصاص رنگ‌ها و نام‌های سفارشی به آنها سفارشی کنید. پیش از این، رویدادها به مجموعه‌ای ثابت از رنگ‌های مبتنی بر شاخص ( colorId ) محدود بودند. با برچسب‌ها، می‌توانید یک پالت رنگی انعطاف‌پذیر و سفارشی برای هر تقویم تعریف کنید و این برچسب‌ها را مستقیماً به رویدادها اعمال کنید.

این ویژگی جایگزین فیلد colorId قدیمی مبتنی بر شاخص می‌شود. برای استفاده از برچسب‌ها، باید پارامتر eventLabelVersion=1 را در درخواست‌های API خود مشخص کنید. وقتی این پارامتر تنظیم شود، فیلد colorId قدیمی نادیده گرفته می‌شود.

مدیریت برچسب‌ها در تقویم

شما می‌توانید با استفاده از ویژگی labelProperties در منبع Calendars ، تا ۲۰۰ برچسب سفارشی برای هر تقویم تعریف کنید.

برای مدیریت برچسب‌ها، از متدهای Calendars.insert یا Calendars.update استفاده کنید. هر برچسب به یک id ، یک backgroundColor با فرمت هگزادسیمال و یک name اختیاری نیاز دارد.

توجه: برای تعریف یا تغییر برچسب‌های یک تقویم، باید به آن دسترسی owner access) داشته باشید.

نمایش منابع تقویم

{
  "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 ) و به‌روزرسانی تقویم را نشان می‌دهند:

برو

// 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}`);
  });
});

پایتون

# 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 خام زیر، درخواست 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 تنظیم یا تغییر دهید.

توجه: برای اختصاص برچسب به رویدادهای یک تقویم، باید حداقل دسترسی writerWithoutPrivateAccess (یا بالاتر: writer یا owner ) به آن داشته باشید.

به یاد داشته باشید: برای پردازش این فیلد، باید ?eventLabelVersion=1 را به آدرس اینترنتی درخواست خود اضافه کنید.

نمایش منابع رویداد

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

مثال: ایجاد یک رویداد با برچسب

نمونه‌های زیر نحوه ایجاد یک رویداد با برچسب سفارشی را نشان می‌دهند:

برو

// 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}`);
});

پایتون

# 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')}")

اچ‌تی‌پی

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 حذف کنید.

برچسب ها با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

مدیریت برچسب‌ها در تقویم

نمایش منابع تقویم

مثال: اضافه کردن و حذف برچسب‌ها در یک تقویم

برو

جاوا

جاوا اسکریپت

پایتون

اچ‌تی‌پی

اختصاص برچسب به رویدادها

نمایش منابع رویداد

مثال: ایجاد یک رویداد با برچسب

برو

جاوا

جاوا اسکریپت

پایتون

اچ‌تی‌پی

برچسب ها