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

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

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

يشبه إنشاء أحداث متكرّرة إنشاء حدث عادي (فردي) باستخدام مجموعة الحقل 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...
    },
    # ...
  ],
}

Java

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()، يتصرف كما لو كانت 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
  }
}

Java

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