تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

يمكنك الاتصال بالرقم events.update() لقطع الحدث الأصلي المتكرر للمثيلات ليتم تعديلها. يمكنك إجراء ذلك من خلال ضبط المكوِّن UNTIL في RRULE على الإشارة قبل وقت بدء المثيل الهدف الأول. يمكنك بدلاً من ذلك ضبط المكوِّن COUNT بدلاً من UNTIL.
يمكنك الاتصال بـ 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...
    },
    # ...
  ],
}