Events: instances

عرض أمثلة من الحدث المتكرّر المحدّد جرِّب الخدمة الآن أو اطّلِع على مثال.

الطلب

طلب HTTP

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId/instances

المعلمات

اسم المعلَمة القيمة الوصف
مَعلمات المسار
calendarId string معرِّف التقويم. لاسترداد معرّفات التقويم، يجب استدعاء الطريقة calendarList.list. إذا أردت الوصول إلى التقويم الأساسي للمستخدم الذي سجّل الدخول حاليًا، استخدِم "primary" .
eventId string معرّف الحدث المتكرر.
مَعلمات طلب البحث الاختيارية
alwaysIncludeEmail boolean تم إيقافها وتجاهلها. سيتم دائمًا عرض قيمة في الحقل email للمنظِّم والمنشئ والحضور، حتى في حال عدم توفّر عنوان بريد إلكتروني حقيقي (أي سيتم تقديم قيمة منشأة وغير عاملة).
maxAttendees integer الحد الأقصى لعدد الضيوف المطلوب تضمينهم في الرد. فإذا كان عدد الحاضرين أكثر من العدد المحدد، فسيتم عرض المشارك فقط. اختياريّ.
maxResults integer الحدّ الأقصى لعدد الأحداث التي يتم عرضها على صفحة نتائج واحدة تكون القيمة تلقائيًا 250 حدثًا. لا يمكن أن يزيد حجم الصفحة عن 2500 حدث. اختياريّ.
originalStart string وقت البدء الأصلي للمثيل في النتيجة. اختياريّ.
pageToken string رمز مميز يحدد صفحة النتائج التي سيتم عرضها. اختياريّ.
showDeleted boolean لتحديد ما إذا كان سيتم تضمين الأحداث المحذوفة (مع أن status يساوي "cancelled") في النتيجة. أمّا في حال ضبط السياسة singleEvents على القيمة "خطأ"، فسيستمر ذلك ضِمن الأحداث الملغاة. اختياريّ. وتكون القيمة التلقائية False.
timeMax datetime الحد الأقصى (حصريًا) لوقت بدء الحدث المطلوب الفلترة حسبه. اختياريّ. الإعداد التلقائي هو عدم الفلترة حسب وقت البدء. يجب أن يكون طابعًا زمنيًا من نوع RFC3339 مع معادلة إلزامية للمنطقة الزمنية.
timeMin datetime الحد الأدنى (شامل) لوقت انتهاء الحدث المطلوب الفلترة حسبه. اختياريّ. الإعداد التلقائي هو عدم الفلترة حسب وقت الانتهاء. يجب أن يكون طابعًا زمنيًا من نوع RFC3339 مع معادلة إلزامية للمنطقة الزمنية.
timeZone string المنطقة الزمنية المستخدَمة في الردّ اختياريّ. تكون المنطقة الزمنية التلقائية للتقويم.

التفويض

يسمح هذا الطلب بالتفويض باستخدام نطاق واحد على الأقل من النطاقات التالية:

النطاق
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events.readonly
https://www.googleapis.com/auth/calendar.events

لمزيد من المعلومات، يُرجى الاطّلاع على صفحة المصادقة والتفويض.

نص الطلب

لا تقدِّم نص طلب باستخدام هذه الطريقة.

الرد

في حال نجاح هذه الطريقة، سيتم عرض نص استجابة بالبنية التالية:

{
  "kind": "calendar#events",
  "etag": etag,
  "summary": string,
  "description": string,
  "updated": datetime,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      "method": string,
      "minutes": integer
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "items": [
    events Resource
  ]
}
اسم الموقع القيمة الوصف ملاحظات
kind string نوع المجموعة ("calendar#events").
etag etag علامة ETag للمجموعة.
summary string عنوان التقويم. للقراءة فقط.
description string وصف التقويم. للقراءة فقط.
updated datetime وقت آخر تعديل للتقويم (كطابع زمني RFC3339) للقراءة فقط.
timeZone string المنطقة الزمنية للتقويم. للقراءة فقط.
accessRole string دور وصول المستخدم إلى هذا التقويم للقراءة فقط. القيم المتاحة:
  • "none" - لا يمتلك المستخدم حق الوصول.
  • "freeBusyReader" - يتوفر لدى المستخدم إذن وصول للقراءة إلى معلومات الحالة متوفّر/مشغول.
  • "reader" - يمتلك المستخدم إذنًا بقراءة التقويم. وستظهر الأحداث الخاصة للمستخدمين الذين لديهم إذن وصول القرّاء، ولكن سيتم إخفاء تفاصيلها.
  • "writer" - يمتلك المستخدم إذنًا بقراءة التقويم والكتابة فيه. وستظهر الأحداث الخاصة للمستخدمين الذين لديهم إذن وصول المؤلف، وستظهر تفاصيل الحدث.
  • "owner" - يمتلك المستخدم ملكية التقويم. ويشمل هذا الدور جميع الأذونات الممنوحة لدور الكاتب بالإضافة إلى إمكانية الاطّلاع على قوائم التحكم بالوصول (ACLs) ومعالجتها.
defaultReminders[] list التذكيرات التلقائية في التقويم للمستخدم الذي تمت مصادقته. تنطبق هذه التذكيرات على جميع الأحداث في هذا التقويم التي لا تتجاهلها بشكل صريح (أي لم يتم ضبط reminders.useDefault على "صحيح").
defaultReminders[].method string الطريقة المستخدمة في هذا التذكير القيم المتاحة:
  • "email" - يتم إرسال التذكيرات عبر البريد الإلكتروني.
  • "popup" - يتم إرسال التذكيرات عبر نافذة منبثقة لواجهة المستخدم.

مطلوب عند إضافة تذكير.

 قابل للكتابة
defaultReminders[].minutes integer عدد الدقائق التي تسبق بدء الحدث والتي من المفترض أن يبدأ فيها التذكير. تتراوح القيم الصالحة بين 0 و40320 (4 أسابيع بالدقائق).

مطلوب عند إضافة تذكير.

 قابل للكتابة
nextPageToken string الرمز المميّز المستخدَم للوصول إلى الصفحة التالية من هذه النتيجة. يتم حذف البيانات إذا لم تتوفر نتائج إضافية، وفي هذه الحالة يتم تقديم nextSyncToken.
items[] list قائمة الأحداث في التقويم
nextSyncToken string يتم استخدام الرمز المميز في وقت لاحق لاسترداد الإدخالات التي تم تغييرها منذ عرض هذه النتيجة فقط. يتم حذف البيانات في حال توفُّر نتائج إضافية، وفي هذه الحالة يتم توفير nextPageToken.

أمثلة

ملاحظة: إنّ الأمثلة المرتبطة بالرموز والمتوفرة لهذه الطريقة لا تمثّل كل لغات البرمجة المتوافقة (يُرجى مراجعة صفحة مكتبات البرامج للاطّلاع على قائمة باللغات المتوافقة).

Java

تستخدم مكتبة برامج Java.

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.Events;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Iterate over the instances of a specific recurring event
String pageToken = null;
do {
  Events events =
      service.events().instances('primary', 'eventId').setPageToken(pageToken).execute();
  List<Event> items = events.getItems();
  for (Event event : items) {
    System.out.println(event.getSummary());
  }
  pageToken = events.getNextPageToken();
} while (pageToken != null);

Python

تستخدم مكتبة برامج Python.

page_token = None
while True:
  events = service.events().instances(calendarId='primary', eventId='eventId',
                                      pageToken=page_token).execute()
  for event in events['items']:
    print event['summary']
  page_token = events.get('nextPageToken')
  if not page_token:
    break

PHP

لاستخدام مكتبة برامج PHP

$events = $service->events->instances('primary', "eventId");

while(true) {
  foreach ($events->getItems() as $event) {
    echo $event->getSummary();
  }
  $pageToken = $events->getNextPageToken();
  if ($pageToken) {
    $optParams = array('pageToken' => $pageToken);
    $events = $service->events->instances('primary', "eventId",
        $optParams);
  } else {
    break;
  }
}

Ruby

تستخدم مكتبة برامج Ruby.

page_token = nil
begin
  result = client.list_event_instances('primary', 'eventId')
  result.items.each do |e|
    print e.summary + "\n"
  end
  if result.next_page_token != page_token
    page_token = result.next_page_token
  else
    page_token = nil
  end
end while !page_token.nil?

جرّب الآن

يمكنك استخدام "مستكشف واجهات برمجة التطبيقات" أدناه لطلب هذه الطريقة على البيانات المباشرة والاطّلاع على الردّ.