דף זה תורגם על ידי 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.

הערה: אפשר להשתמש בערך המיוחד primary של calendarId כדי להתייחס ליומן הראשי של המשתמשים המאומתים.

לאחר ההצלחה, השרת מגיב עם קוד סטטוס 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() אל ליצור אירוע חוזר חדש עם כל אותם נתונים כמו במקור, מלבד השינוי שניסית לבצע. שעת ההתחלה של האירוע החוזר החדש חייבת להיות מופע היעד.

בדוגמה הזו ניתן לראות איך לשנות את המיקום ל'מיקום אחר', החל מהמיקום השלישי של האירוע החוזר מהדוגמאות הקודמות.

פרוטוקול

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