Events: list

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

الطلب

طلب HTTP

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

المعلمات

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

القِيَم المقبولة هي:
  • "birthday": أحداث خاصة تستمر على مدار اليوم وتتكرّر سنويًا.
  • "default": الأحداث العادية
  • "focusTime": أحداث وقت التركيز
  • "fromGmail": أحداث من Gmail
  • "outOfOffice": أحداث خارج المكتب
  • "workingLocation": أحداث مكان العمل
iCalUID string تُستخدَم لتحديد رقم تعريف حدث بتنسيق iCalendar ليتم تقديمه في الردّ. اختياريّ. استخدِم هذا الإجراء إذا أردت البحث عن حدث باستخدام معرّفه في iCalendar.
maxAttendees integer الحد الأقصى لعدد الضيوف المطلوب تضمينه في الردّ إذا كان هناك أكثر من العدد المحدّد من الضيوف، يتم عرض المشارك فقط. اختياريّ.
maxResults integer الحد الأقصى لعدد الأحداث التي يتم عرضها في صفحة نتائج واحدة قد يكون عدد الأحداث في الصفحة الناتجة أقل من هذه القيمة، أو قد لا يكون هناك أي أحداث على الإطلاق، حتى إذا كانت هناك أحداث أخرى تتطابق مع الطلب. يمكن رصد الصفحات غير المكتملة من خلال حقل nextPageToken غير فارغ في الاستجابة. تكون القيمة التلقائية هي 250 حدثًا. لا يمكن أن يزيد حجم الصفحة عن 2500 حدث. اختياريّ.
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

تتطابق عبارات البحث هذه أيضًا مع كلمات رئيسية محدّدة مسبقًا مقابل جميع ترجمات العناوين المعروضة لأحداث مكان العمل ووقت العمل خارج المكتب ووقت التركيز. على سبيل المثال، يؤدي البحث عن "مكتب" أو "Bureau" إلى عرض أحداث مكان العمل من النوع officeLocation، في حين يؤدي البحث عن "خارج المكتب" أو "Abwesend" إلى عرض أحداث "خارج المكتب". اختياريّ.
sharedExtendedProperty string قيد الخصائص الموسعة المحدد على PropertyName=value. تتطابق مع السمات المشتركة فقط. قد يتم تكرار هذه المَعلمة عدة مرات لعرض الأحداث التي تتطابق مع جميع القيود المحدّدة.
showDeleted boolean ما إذا كان سيتم تضمين الأحداث المحذوفة (مع status يساوي "cancelled") في النتيجة. سيستمر تضمين النُسخ المُلغاة من الأحداث المتكرّرة (ولكن ليس الحدث المتكرّر الأساسي) إذا كانت كلّ من showDeleted وsingleEvents غير صحيحة. إذا كان كلا الحقلين showDeleted وsingleEvents صحيحَين، يتم عرض أحداث فردية محذوفة فقط (وليس الأحداث المتكرّرة الأساسية). اختياريّ. القيمة التلقائية هي False.
showHiddenInvitations boolean ما إذا كنت تريد تضمين الدعوات المخفية في النتيجة اختياريّ. القيمة التلقائية هي False.
singleEvents boolean ما إذا كان سيتم توسيع الأحداث المتكرّرة إلى نُسخ وعرض الأحداث الفردية وأحداث النُسخ من الأحداث المتكرّرة فقط، وليس الأحداث المتكرّرة الأساسية نفسها. اختياريّ. القيمة التلقائية هي False.
syncToken string الرمز المميّز الذي تم الحصول عليه من الحقل nextSyncToken الذي تم إرجاعه في الصفحة الأخيرة من النتائج من طلب القائمة السابق. تجعل نتيجة طلب القائمة هذا تحتوي فقط على الإدخالات التي تم تغييرها منذ ذلك الحين. ستكون جميع الأحداث التي تم حذفها منذ طلب القائمة السابق في مجموعة النتائج دائمًا، ولا يُسمح بضبط showDeleted على False.
هناك العديد من مَعلمات طلب البحث التي لا يمكن تحديدها مع 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
  ]
}
اسم الموقع القيمة الوصف ملاحظات
kind string نوع المجموعة ("calendar#events").
etag etag علامة ETag للمجموعة
summary string عنوان التقويم. للقراءة فقط.
description string وصف التقويم للقراءة فقط.
updated datetime وقت آخر تعديل على التقويم (كطابع زمني RFC3339) للقراءة فقط.
timeZone string المنطقة الزمنية للتقويم للقراءة فقط.
accessRole string دور وصول المستخدم إلى هذا التقويم. للقراءة فقط. القيم المتاحة:
  • "none" - لا يمكن للمستخدم الوصول إلى البيانات.
  • "freeBusyReader" - يمتلك المستخدم إذن وصول للقراءة إلى معلومات الحالة متوفّر/مشغول.
  • "reader" - يمتلك المستخدم إذنًا بقراءة التقويم. ستظهر الأحداث الخاصة للمستخدمين الذين لديهم إذن وصول "قارئ"، ولكن سيتم إخفاء تفاصيل الحدث.
  • "writer": يمتلك المستخدم إذنًا بالقراءة والكتابة في التقويم. ستظهر الأحداث الخاصة للمستخدمين الذين لديهم إذن وصول بصفتهم كاتبًا، وستظهر تفاصيل الحدث.
  • "owner": يملك المستخدم ملكية التقويم. يمتلك هذا الدور جميع أذونات دور "الكاتب" مع إمكانية إضافية للاطّلاع على جداول أذونات الوصول وتعديلها.
defaultReminders[] list التذكيرات التلقائية في التقويم للمستخدم الذي تم مصادقة هويته تنطبق هذه التذكيرات على جميع الأحداث في هذا التقويم التي لا تلغي هذه التذكيرات صراحةً (أي أنّها لا تضبط reminders.useDefault على True).
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?

جرّب الآن

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