رویدادهای تکراری

این سند نحوه کار با رویدادهای تکرارشونده و نمونه‌های آنها را شرح می‌دهد.

ایجاد رویدادهای تکرارشونده

ایجاد رویدادهای تکرارشونده مشابه ایجاد یک رویداد معمولی (تکی) با تنظیم فیلد recurrence منبع Event است.

پروتکل

POST /calendar/v3/calendars/primary/events
...

{
  "summary": "Appointment",
  "location": "Somewhere",
  "start": {
    "dateTime": "2011-06-03T10:00:00.000-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "end": {
    "dateTime": "2011-06-03T10:25:00.000-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "recurrence": [
    "RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z",
  ],
  "attendees": [
    {
      "email": "attendeeEmail",
      # Other attendee's data...
    },
    # ...
  ],
}

جاوا

Event event = new Event();

event.setSummary("Appointment");
event.setLocation("Somewhere");

ArrayList<EventAttendee> attendees = new ArrayList<EventAttendee>();
attendees.add(new EventAttendee().setEmail("attendeeEmail"));
// ...
event.setAttendees(attendees);

DateTime start = DateTime.parseRfc3339("2011-06-03T10:00:00.000-07:00");
DateTime end = DateTime.parseRfc3339("2011-06-03T10:25:00.000-07:00");
event.setStart(new EventDateTime().setDateTime(start).setTimeZone("America/Los_Angeles"));
event.setEnd(new EventDateTime().setDateTime(end).setTimeZone("America/Los_Angeles"));
event.setRecurrence(Arrays.asList("RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z"));

Event recurringEvent = service.events().insert("primary", event).execute();

System.out.println(createdEvent.getId());

دات نت

Event event = new Event()
    {
      Summary = "Appointment",
      Location = "Somewhere",
      Start = new EventDateTime() {
          DateTime = new DateTime("2011-06-03T10:00:00.000:-07:00")
          TimeZone = "America/Los_Angeles"
      },
      End = new EventDateTime() {
          DateTime = new DateTime("2011-06-03T10:25:00.000:-07:00")
          TimeZone = "America/Los_Angeles"
      },
      Recurrence = new String[] {
          "RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z"
      },
      Attendees = new List<EventAttendee>()
          {
            new EventAttendee() { Email: "attendeeEmail" },
            // ...
          }
    };

Event recurringEvent = service.Events.Insert(event, "primary").Fetch();

Console.WriteLine(recurringEvent.Id);

پایتون

event = {
  'summary': 'Appointment',
  'location': 'Somewhere',
  'start': {
    'dateTime': '2011-06-03T10:00:00.000-07:00',
    'timeZone': 'America/Los_Angeles'
  },
  'end': {
    'dateTime': '2011-06-03T10:25:00.000-07:00',
    'timeZone': 'America/Los_Angeles'
  },
  'recurrence': [
    'RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z',
  ],
  'attendees': [
    {
      'email': 'attendeeEmail',
      # Other attendee's data...
    },
    # ...
  ],
}

recurring_event = service.events().insert(calendarId='primary', body=event).execute()

print recurring_event['id']

پی اچ پی

$event = new Google_Service_Calendar_Event();
$event->setSummary('Appointment');
$event->setLocation('Somewhere');
$start = new Google_Service_Calendar_EventDateTime();
$start->setDateTime('2011-06-03T10:00:00.000-07:00');
$start->setTimeZone('America/Los_Angeles');
$event->setStart($start);
$end = new Google_Service_Calendar_EventDateTime();
$end->setDateTime('2011-06-03T10:25:00.000-07:00');
$end->setTimeZone('America/Los_Angeles');
$event->setEnd($end);
$event->setRecurrence(array('RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z'));
$attendee1 = new Google_Service_Calendar_EventAttendee();
$attendee1->setEmail('attendeeEmail');
// ...
$attendees = array($attendee1,
                   // ...
                   );
$event->attendees = $attendees;
$recurringEvent = $service->events->insert('primary', $event);

echo $recurringEvent->getId();

روبی

event = Google::Apis::CalendarV3::Event.new(
  summary: 'Appointment',
  location: 'Somewhere',
  start: {
    date_time: '2011-06-03T10:00:00.000-07:00',
    time_zone:  'America/Los_Angeles'
  },
  end: {
    date_time: '2011-06-03T10:25:00.000-07:00',
    time_zone: 'America/Los_Angeles'
  },
  recurrence: ['RRULE:FREQ=WEEKLY;UNTIL=20110701T170000Z']
  attendees: [
    {
      email: 'attendeeEmail'
    },
    #...
  ]
)
response = client.insert_event('primary', event)
print response.id

دسترسی به نمونه‌ها

برای مشاهده‌ی تمام نمونه‌های یک رویداد تکرارشونده، از متد events.instances استفاده کنید.

به طور پیش‌فرض، متد events.list رویدادهای تکی، رویدادهای تکرارشونده و استثناها را برمی‌گرداند؛ نمونه‌هایی که استثنا نیستند، برگردانده نمی‌شوند. اگر پارامتر singleEvents روی true تنظیم شود، تمام نمونه‌های منفرد در نتیجه ظاهر می‌شوند، اما رویدادهای تکرارشونده اصلی نمایش داده نمی‌شوند. وقتی کاربری که مجوزهای free/busy دارد، events.list را جستجو می‌کند، طوری رفتار می‌کند که انگار singleEvents true است. برای اطلاعات بیشتر در مورد قوانین لیست کنترل دسترسی، به ACL مراجعه کنید.

نمونه‌های منفرد مشابه رویدادهای تکی هستند. برخلاف رویدادهای تکرارشونده والدشان، نمونه‌ها فیلد recurrence را ندارند.

فیلدهای رویداد زیر مختص نمونه‌ها هستند:

  • recurringEventId - شناسه رویداد تکرارشونده والد که این نمونه به آن تعلق دارد
  • originalStartTime — زمانی که این نمونه طبق داده‌های بازگشتی در رویداد تکرارشونده والد شروع می‌شود. اگر نمونه دوباره زمان‌بندی شده باشد، این می‌تواند با زمان start واقعی متفاوت باشد. این پارامتر، نمونه را در سری رویدادهای تکرارشونده، حتی اگر نمونه جابجا شده باشد، به طور منحصر به فرد مشخص می‌کند.

تغییر یا حذف نمونه‌ها

برای تغییر یک نمونه (ایجاد یک استثنا)، برنامه‌های کلاینت ابتدا باید نمونه را بازیابی کرده و سپس با ارسال یک درخواست PUT مجاز به URL ویرایش نمونه با داده‌های به‌روزرسانی‌شده در بدنه، آن را به‌روزرسانی کنند. URL به شکل زیر است:

https://www.googleapis.com/calendar/v3/calendars/calendarId/events/instanceId

به جای calendarId و instanceId از مقادیر مناسب استفاده کنید.

پس از موفقیت، سرور با یک کد وضعیت HTTP 200 OK به همراه نمونه به‌روزرسانی‌شده پاسخ می‌دهد. مثال زیر نحوه لغو یک نمونه از یک رویداد تکرارشونده را نشان می‌دهد.

پروتکل

PUT /calendar/v3/calendars/primary/events/instanceId
...

{
  "kind": "calendar#event",
  "id": "instanceId",
  "etag": "instanceEtag",
  "status": "cancelled",
  "htmlLink": "https://www.google.com/calendar/event?eid=instanceEid",
  "created": "2011-05-23T22:27:01.000Z",
  "updated": "2011-05-23T22:27:01.000Z",
  "summary": "Recurring event",
  "location": "Somewhere",
  "creator": {
    "email": "userEmail"
  },
  "recurringEventId": "recurringEventId",
  "originalStartTime": "2011-06-03T10:00:00.000-07:00",
  "organizer": {
    "email": "userEmail",
    "displayName": "userDisplayName"
  },
  "start": {
    "dateTime": "2011-06-03T10:00:00.000-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "end": {
    "dateTime": "2011-06-03T10:25:00.000-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "iCalUID": "eventUID",
  "sequence": 0,
  "attendees": [
    {
      "email": "attendeeEmail",
      "displayName": "attendeeDisplayName",
      "responseStatus": "needsAction"
    },
    # ...
    {
      "email": "userEmail",
      "displayName": "userDisplayName",
      "responseStatus": "accepted",
      "organizer": true,
      "self": true
    }
  ],
  "guestsCanInviteOthers": false,
  "guestsCanSeeOtherGuests": false,
  "reminders": {
    "useDefault": true
  }
}

جاوا

// First retrieve the instances from the API.
Events instances = service.events().instances("primary", "recurringEventId").execute();

// Select the instance to cancel.
Event instance = instances.getItems().get(0);
instance.setStatus("cancelled");

Event updatedInstance = service.events().update("primary", instance.getId(), instance).execute();

// Print the updated date.
System.out.println(updatedInstance.getUpdated());

دات نت

// First retrieve the instances from the API.
Events instances = service.Events.Instances("primary", "recurringEventId").Fetch();

// Select the instance to cancel.
Event instance = instances.Items[0];
instance.Status = "cancelled";

Event updatedInstance = service.Events.Update(instance, "primary", instance.Id).Fetch();

// Print the updated date.
Console.WriteLine(updatedInstance.Updated);

پایتون

# First retrieve the instances from the API.
instances = service.events().instances(calendarId='primary', eventId='recurringEventId').execute()

# Select the instance to cancel.
instance = instances['items'][0]
instance['status'] = 'cancelled'

updated_instance = service.events().update(calendarId='primary', eventId=instance['id'], body=instance).execute()

# Print the updated date.
print updated_instance['updated']

پی اچ پی

$events = $service->events->instances("primary", "eventId");

// Select the instance to cancel.
$instance = $events->getItems()[0];
$instance->setStatus('cancelled');

$updatedInstance = $service->events->update('primary', $instance->getId(), $instance);

// Print the updated date.
echo $updatedInstance->getUpdated();

روبی

# First retrieve the instances from the API.
instances = client.list_event_instances('primary', 'recurringEventId')

# Select the instance to cancel.
instance = instances.items[0]
instance.status = 'cancelled'

response = client.update_event('primary', instance.id, instance)
print response.updated

تمام موارد زیر را اصلاح کنید

برای تغییر تمام نمونه‌های یک رویداد تکرارشونده روی یا بعد از یک نمونه (هدف) مشخص، دو درخواست API جداگانه ارسال کنید. این درخواست‌ها رویداد تکرارشونده اصلی را به دو قسمت تقسیم می‌کنند: رویداد اصلی که نمونه‌هایی را بدون تغییر نگه می‌دارد و رویداد تکرارشونده جدید که نمونه‌هایی دارد که تغییر در آنها اعمال می‌شود:

  1. برای حذف رویداد تکرارشونده اصلی نمونه‌هایی که قرار است به‌روزرسانی شوند، از events.update استفاده کنید. این کار را با تنظیم مؤلفه UNTIL از RRULE به قبل از زمان شروع اولین نمونه هدف انجام دهید. به عنوان یک روش جایگزین، می‌توانید مؤلفه COUNT را به جای UNTIL تنظیم کنید.
  2. برای ایجاد یک رویداد تکرارشونده جدید با تمام داده‌های مشابه رویداد اصلی، به جز تغییری که ایجاد می‌کنید، از events.insert استفاده کنید. رویداد تکرارشونده جدید باید زمان شروع نمونه هدف را داشته باشد.

این مثال نشان می‌دهد که چگونه می‌توان مکان را به «جایی دیگر» تغییر داد، و از سومین نمونه از رویداد تکرارشونده از مثال‌های قبلی شروع کرد.

پروتکل

# Updating the original recurring event to trim the instance list:

PUT /calendar/v3/calendars/primary/events/recurringEventId
...

{
  "summary": "Appointment",
  "location": "Somewhere",
  "start": {
    "dateTime": "2011-06-03T10:00:00.000-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "end": {
    "dateTime": "2011-06-03T10:25:00.000-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "recurrence": [
    "RRULE:FREQ=WEEKLY;UNTIL=20110617T065959Z",
  ],
  "attendees": [
    {
      "email": "attendeeEmail",
      # Other attendee's data...
    },
    # ...
  ],
}


# Creating a new recurring event with the change applied:

POST /calendar/v3/calendars/primary/events
...

{
  "summary": "Appointment",
  "location": "Somewhere else",
  "start": {
    "dateTime": "2011-06-17T10:00:00.000-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "end": {
    "dateTime": "2011-06-17T10:25:00.000-07:00",
    "timeZone": "America/Los_Angeles"
  },
  "recurrence": [
    "RRULE:FREQ=WEEKLY",
  ],
  "attendees": [
    {
      "email": "attendeeEmail",
      # Other attendee's data...
    },
    # ...
  ],
}