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

تتطابق عبارات البحث هذه أيضًا مع كلمات رئيسية محدّدة مسبقًا مقابل جميع ترجمات العناوين المعروضة لأحداث مكان العمل ووقت العمل خارج المكتب ووقت التركيز. على سبيل المثال، يؤدي البحث عن "Office" أو "Bureau" إلى عرض أحداث مكان العمل من النوع officeLocation، في حين يؤدي البحث عن "Out of office" أو "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
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.freebusy
https://www.googleapis.com/auth/calendar.events.owned
https://www.googleapis.com/auth/calendar.events.owned.readonly
https://www.googleapis.com/auth/calendar.events.public.readonly

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

نص الطلب

لا تقدِّم محتوى طلب باستخدام هذه الطريقة.

الردّ

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

{
  "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.

جرّب الآن

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