Events: list

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

الطلب

طلب HTTP

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

المعلمات

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

في ما يلي القيم المقبولة:
  • "default": أحداث منتظمة
  • "focusTime": أحداث وقت التركيز
  • "fromGmail": أحداث من Gmail
  • "outOfOffice": أحداث خارج المكتب
  • "workingLocation": أحداث مكان العمل
iCalUID string تحدِّد هذه السياسة رقم تعريف حدث بتنسيق iتقويم الذي سيتم توفيره في الردّ. اختياريّ. استخدِم هذا الخيار إذا كنت تريد البحث عن حدث باستخدام معرّف iتقويم Google.
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

تعمل عبارات البحث هذه أيضًا على مطابقة الكلمات الرئيسية المحددة مسبقًا مع جميع ترجمات العنوان المعروض لمكان العمل، وخارج المكتب، وأحداث وقت التركيز. على سبيل المثال، سيؤدي البحث عن "Office" أو "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 على "خطأ".
هناك العديد من مَعلمات طلب البحث التي لا يمكن تحديدها مع 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" - يمتلك المستخدم ملكية التقويم. ويشمل هذا الدور جميع الأذونات الممنوحة لدور الكاتب بالإضافة إلى إمكانية الاطّلاع على قوائم التحكم بالوصول (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 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?

جرّب الآن

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