الأحداث المتكررة

توضّح هذه المقالة كيفية استخدام الأحداث المتكرّرة ومثيلاتها.

إنشاء أحداث متكررة

يشبه إنشاء أحداث متكرّرة إنشاء حدث عادي (واحد) مع ضبط حقل recurrence في مورد الحدث.

البروتوكول

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());

NET.

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);

Python

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();

Ruby

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، يتم التعامل معها كما لو أنّ 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());

NET.

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

Python

# 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();

Ruby

# 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

تعديل جميع المثيلات التالية

لتغيير جميع مثيلات حدث متكرّر في مثيل معيّن (مستهدف) أو بعده، عليك إرسال طلبَين منفصلَين إلى واجهة برمجة التطبيقات. يقسّم هذان الطلبان الحدث المتكرّر الأصلي إلى حدثَين: الحدث الأصلي الذي يحتفظ بالمثيلات بدون التغيير، والحدث المتكرّر الجديد الذي يتضمّن مثيلات تم تطبيق التغيير عليها:

  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...
    },
    # ...
  ],
}