Events: list

عرض الأحداث في التقويم المحدد. جرِّبه الآن أو شاهد مثالاً.

الطلب

طلب HTTP

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

المَعلمات

اسم المعلَمة القيمة الوصف
مَعلمات المسار
calendarId string معرِّف التقويم. لاسترداد معرّفات التقويم، يمكنك استدعاء الطريقة calendarList.list. إذا كنت تريد الوصول إلى التقويم الأساسي للمستخدم المسجّل دخوله حاليًا، استخدِم الكلمة الرئيسية "primary".
مَعلمات طلب البحث الاختيارية
alwaysIncludeEmail boolean تم التجاهل وتم تجاهله.
eventTypes string أنواع الأحداث المطلوب عرضها. اختياريّ. ويمكن تكرار هذه المَعلمة عدة مرات لعرض أحداث من أنواع مختلفة. والقيمة التلقائية هي ["default", "focusTime", "outOfOffice"].

القيم المقبولة هي:
  • "default": الأحداث المنتظمة
  • "focusTime": أحداث وقت التركيز
  • "outOfOffice": أحداث خارج المكتب
  • "workingLocation": أحداث مكان العمل
iCalUID string تحدِّد هذه السياسة رقم تعريف حدث بتنسيق iالتقويم الذي سيتم تقديمه في الاستجابة. اختياريّ. ويمكنك استخدام هذا الخيار إذا كنت تريد البحث عن حدث باستخدام معرّف iالتقويم.
maxAttendees integer تمثّل هذه السمة الحد الأقصى لعدد الضيوف الذين سيتم تضمينهم في الرد. إذا كان هناك أكثر من العدد المحدّد من الضيوف، يتم عرض المشارك فقط. اختياريّ.
maxResults integer الحدّ الأقصى لعدد الأحداث التي يتم عرضها في صفحة نتائج واحدة قد يكون عدد الأحداث في الصفحة الناتجة أقل من هذه القيمة، أو قد لا يكون أيًا منها على الإطلاق، حتى إذا كان هناك المزيد من الأحداث المتطابقة مع طلب البحث. يمكن رصد الصفحات غير المكتملة من خلال حقل nextPageToken غير فارغ في الاستجابة. وبشكلٍ تلقائي، تكون القيمة 250 حدثًا. لا يمكن أبدًا أن يتجاوز حجم الصفحة 2,500 حدث. اختياريّ.
orderBy string ترتيب الأحداث المعروضة في النتيجة. اختياريّ. والترتيب التلقائي هو ترتيب ثابت وغير محدَّد.

القيم المقبولة هي:
  • "startTime": ترتيب حسب تاريخ/وقت البدء (ترتيب تصاعدي) لا يتوفّر هذا إلّا عند إجراء طلبات بحث عن أحداث فردية (أي أنّ المَعلمة singleEvents تكون True).
  • "updated": ترتيب تصاعدي حسب وقت آخر تعديل
pageToken string رمز مميز يحدد صفحة النتائج المراد عرضها اختياريّ.
privateExtendedProperty string قيد الخصائص الموسعة محدد على أنه PropertyName=value. يطابق الممتلكات الخاصة فقط. قد يتم تكرار هذه المَعلمة عدة مرات لعرض أحداث تتطابق مع جميع القيود المحدّدة.
q string عبارات البحث النصي المجاني للعثور على الأحداث التي تطابق هذه العبارات في الحقول التالية:
  • summary
  • description
  • location
  • displayName للضيف
  • email للضيف
  • displayName للمنظِّم
  • email للمنظِّم
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

وتعمل عبارات البحث هذه أيضًا على مطابقة الكلمات الرئيسية المحدَّدة مسبقًا مقابل جميع ترجمات العنوان المعروض لمكان العمل وخارج المكتب وأحداث وقت التركيز. على سبيل المثال، يؤدي البحث عن "Office" أو "Bureau" إلى عرض أحداث مكان العمل من النوع officeLocation، بينما يؤدي البحث عن "خارج المكتب" أو "Abwesend" إلى عرض أحداث خارج المكتب. اختياريّ.

sharedExtendedProperty string قيد الخصائص الموسعة محدد على أنه PropertyName=value. تتطابق فقط مع المواقع المشتركة. قد يتم تكرار هذه المَعلمة عدة مرات لعرض أحداث تتطابق مع جميع القيود المحدّدة.
showDeleted boolean لتحديد ما إذا كان سيتم تضمين الأحداث المحذوفة (مع status يساوي "cancelled") في النتيجة. سيستمر تضمين الأحداث الملغاة للأحداث المتكرّرة (وليس الحدث المتكرّر الأساسي) إذا كان كلٌ من showDeleted وsingleEvents خطأ. إذا كان كل من showDeleted وsingleEvents True، فلن يتم عرض سوى حدث واحد من الأحداث المحذوفة (وليس الأحداث المتكررة الأساسية). اختياريّ. القيمة التلقائية هي False.
showHiddenInvitations boolean ما إذا كان سيتم تضمين دعوات مخفية في النتيجة أم لا. اختياريّ. القيمة التلقائية هي False.
singleEvents boolean تحديد ما إذا كان سيتم توسيع الأحداث المتكررة إلى مثيلات وعرض الأحداث الفردية ومثيلات الأحداث المتكررة فقط، لكن ليس الأحداث المتكررة الأساسية نفسها. اختياريّ. القيمة التلقائية هي False.
syncToken string تم الحصول على رمز مميّز من الحقل nextSyncToken في الصفحة الأخيرة من النتائج من طلب القائمة السابق. ويجعل نتيجة طلب القائمة هذا تحتوي فقط على الإدخالات التي تم تغييرها منذ ذلك الحين. تم حذف جميع الأحداث لأنّ طلب القائمة السابق ستظل دائمًا في مجموعة النتائج، ولا يُسمح بضبط showDeleted على "خطأ".
هناك العديد من مَعلمات طلب البحث التي لا يمكن تحديدها مع nextSyncToken لضمان اتّساق حالة العميل.

هي:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
يجب أن تكون جميع مَعلمات طلب البحث الأخرى هي نفسها المُستخدَمة في المزامنة الأولية لتجنُّب حدوث سلوك غير محدّد. في حال انتهاء صلاحية syncToken، سيستجيب الخادم برمز الاستجابة 410 GONE، ويجب على العميل محو مساحة التخزين وإجراء مزامنة كاملة بدون استخدام أي syncToken.
مزيد من المعلومات حول المزامنة التزايدية
اختيارية. الإعداد التلقائي هو عرض جميع الإدخالات.
timeMax datetime الحد الأعلى (حصري) لوقت بدء الحدث للفلترة حسب هذا الحد. اختياريّ. ويتمثّل الخيار التلقائي في عدم الفلترة حسب وقت البدء. يجب أن يكون الطابع الزمني RFC3339 مع معادلة إلزامية للمنطقة الزمنية، على سبيل المثال، 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. قد يتم توفير مللي ثانية ولكن يتم تجاهلها. إذا تم ضبط timeMin، يجب أن تكون قيمة timeMax أكبر من timeMin.
timeMin datetime الحد الأدنى (حصري) لوقت انتهاء الحدث المطلوب الفلترة حسبه. اختياريّ. ويتمثل الإعداد التلقائي في الفلترة حسب وقت الانتهاء. يجب أن يكون الطابع الزمني RFC3339 مع معادلة إلزامية للمنطقة الزمنية، على سبيل المثال، 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. قد يتم توفير مللي ثانية ولكن يتم تجاهلها. إذا تم ضبط timeMax، يجب أن تكون قيمة timeMin أصغر من timeMax.
timeZone string المنطقة الزمنية المستخدَمة في الردّ. اختياريّ. وتكون المنطقة الزمنية التلقائية هي المنطقة الزمنية للتقويم.
updatedMin datetime الحد الأدنى لوقت آخر تعديل للحدث (كطابع زمني RFC3339) للفلترة وفقًا له. عند التحديد، سيتم تضمين الإدخالات المحذوفة منذ هذه المرة دائمًا بغض النظر عن showDeleted. اختياريّ. ولا يكون الإعداد التلقائي هو الفلترة حسب وقت آخر تعديل.

التفويض

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

النطاق
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
  ]
}
اسم الموقع القيمة الوصف Notes
kind string نوع المجموعة ("calendar#events").
etag etag علامة ETag الخاصة بالمجموعة
summary string عنوان التقويم. للقراءة فقط.
description string وصف التقويم. للقراءة فقط.
updated datetime وقت آخر تعديل للتقويم (كطابع زمني RFC3339). للقراءة فقط.
timeZone string المنطقة الزمنية للتقويم. للقراءة فقط.
accessRole string دور وصول المستخدم إلى هذا التقويم. للقراءة فقط. القيم المتاحة:
  • "none" - لا يملك المستخدم الإذن بالوصول.
  • "freeBusyReader": يملك المستخدم الإذن بالاطّلاع على معلومات الحالة متوفّر/مشغول.
  • "reader" - يتوفر للمستخدم الإذن بالاطّلاع على التقويم. ستظهر الأحداث الخاصة للمستخدمين الذين لديهم إمكانية وصول للقراءة، ولكن سيتم إخفاء تفاصيل الحدث.
  • "writer": يمتلك المستخدم الإذن بالوصول إلى التقويم للقراءة والكتابة. ستظهر الأحداث الخاصة للمستخدمين الذين لديهم إذن وصول الكتاب، وستكون تفاصيل الحدث مرئية.
  • "owner" - يمتلك المستخدم التقويم. يمتلك هذا الدور جميع أذونات دور الكاتب مع إمكانية إضافية رؤية قوائم التحكم في الوصول (ACL) ومعالجتها.
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 events in the specified calendar
String pageToken = null;
do {
  Events events = service.events().list('primary').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().list(calendarId='primary', 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->listEvents('primary');

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

Ruby

تستخدم مكتبة عميل Ruby.

page_token = nil
begin
  result = client.list_events('primary', page_token: page_token)
  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?

تجربة

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