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

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

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

ایجاد رویدادهای تکرارشونده مشابه ایجاد یک رویداد معمولی (تک) با مجموعه فیلدهای 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']

PHP

$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 تنظیم شود، همه نمونه‌های منفرد در نتیجه ظاهر می‌شوند، اما رویدادهای تکرارشونده اساسی اینطور نیستند. وقتی کاربری که مجوزهای آزاد/مشغول دارد events.list() پرس و جو می کند، طوری رفتار می کند که گویی singleEvent true است. برای اطلاعات بیشتر در مورد قوانین لیست کنترل دسترسی، Acl را ببینید.

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

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

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

نمونه ها را اصلاح یا حذف کنید

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

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

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

توجه: مقدار ویژه calendarId primary می تواند برای ارجاع به تقویم اصلی کاربر احراز هویت شده استفاده شود.

پس از موفقیت، سرور با یک کد وضعیت 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']

PHP

$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;UNTIL=20110617T065959Z",
  ],
  "attendees": [
    {
      "email": "attendeeEmail",
      # Other attendee's data...
    },
    # ...
  ],
}