דף זה תורגם על ידי 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 לעריכת המכונה, עם הנתונים המעודכנים בגוף. כתובת האתר היא בתבנית הבאה:

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

שינוי כל המופעים הבאים

כדי לשנות את כל המופעים של אירוע חוזר במופע נתון (יעד) או אחריו, צריך לשלוח שתי בקשות API נפרדות. הבקשות האלה פיצלו את האירוע החוזר המקורי לשניים: האירוע המקורי ששומר את המופעים ללא השינוי, והאירוע החוזר החדש כולל מופעים שבהם השינוי חל:

מפעילים את הפקודה events.update() כדי לחתוך את האירוע החוזר המקורי של המכונות שיש לעדכן. כדי לעשות זאת, מגדירים את הרכיב UNTIL של RRULE כך שיצביע לפני שעת ההתחלה של מופע היעד הראשון. לחלופין, אפשר להגדיר את הרכיב COUNT במקום את UNTIL.
אפשר להפעיל את events.insert() כדי ליצור אירוע חוזר חדש עם כל הנתונים כמו המקור, מלבד השינוי שאתם מנסים לבצע. לאירוע החוזר החדש חייבת להיות שעת ההתחלה של מופע היעד.

בדוגמה הזו מוסבר איך לשנות את המיקום ל-"Somewhere else", החל מהמופע השלישי של האירוע החוזר מהדוגמאות הקודמות.

פרוטוקול

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