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": أحداث خارج المكتب
  • "workingLocation": أحداث مكان العمل
iCalUID string تحدِّد هذه السياسة رقم تعريف حدث بتنسيق icalendar الذي سيتم تقديمه في الردّ. اختياريّ. استخدم هذا الخيار إذا كنت تريد البحث عن حدث باستخدام معرّف iالتقويم.
maxAttendees integer الحد الأقصى لعدد الضيوف الذين سيتم تضمينهم في الرد. وإذا كان هناك أكثر من العدد المحدّد من الضيوف، يتم عرض المشارك فقط. اختياريّ.
maxResults integer الحد الأقصى لعدد الأحداث التي يتم عرضها في صفحة نتائج واحدة. قد يكون عدد الأحداث في الصفحة الناتجة أقل من هذه القيمة أو قد لا يحدث على الإطلاق، حتى إذا كان هناك المزيد من الأحداث المتطابقة مع طلب البحث. يمكن رصد الصفحات غير المكتملة من خلال حقل nextPageToken غير فارغ في الردّ. وتكون القيمة 250 حدثًا تلقائيًا. لا يمكن أبدًا أن يتجاوز حجم الصفحة 2,500 حدث. اختياريّ.
orderBy string ترتيب الأحداث التي تم إرجاعها في النتيجة. اختياريّ. ويكون الترتيب التلقائي هو الترتيب الثابت غير المحدَّد.

القيم المقبولة هي:
  • "startTime": الترتيب حسب تاريخ/وقت البدء (ترتيب تصاعدي) لا يتوفّر هذا إلّا عند إجراء طلبات بحث عن أحداث فردية (أي أنّ المَعلمة singleEvents هي "صحيح").
  • "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 "صحيح"، سيتم عرض أحداث فردية فقط من الأحداث المحذوفة (وليس الأحداث الأساسية المتكررة). اختياريّ. والقيمة التلقائية هي "خطأ".
showHiddenInvitations boolean ما إذا كان سيتم تضمين دعوات مخفية في النتيجة اختياريّ. والقيمة التلقائية هي "خطأ".
singleEvents boolean تحديد ما إذا كان سيتم توسيع الأحداث المتكررة إلى مثيلات وعرض الأحداث لمرة واحدة وحالات الأحداث المتكررة فقط، ولكن ليس الأحداث المتكررة الأساسية نفسها اختياريّ. والقيمة التلقائية هي "خطأ".
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?

تجربة

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