عرض الأحداث في التقويم المحدّد. جرِّبه الآن أو اطّلِع على مثال.
الطلب
طلب HTTP
GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
المَعلمات
اسم المعلَمة | القيمة | الوصف |
---|---|---|
مَعلمات المسار | ||
calendarId |
string |
معرّف التقويم. لاسترداد معرّفات التقويم، يمكنك استدعاء الطريقة calendarList.list. إذا كنت تريد الوصول إلى التقويم الأساسي للمستخدم الذي سجّل دخوله حاليًا، استخدِم الكلمة الرئيسية "primary ".
|
مَعلمات طلب البحث الاختيارية | ||
alwaysIncludeEmail |
boolean |
تم إيقاف العمل به وتجاهله. |
eventTypes |
string |
أنواع الأحداث المطلوب عرضها. اختياريّ. يمكن تكرار هذه المَعلمة عدة مرات لعرض أحداث من أنواع مختلفة. وفي حال ترك هذه السياسة بدون ضبط، سيتم عرض جميع أنواع الأحداث.
القيم المقبولة هي:
|
iCalUID |
string |
تحدِّد هذه السياسة رقم تعريف حدث بتنسيق icalendar الذي سيتم تقديمه في الردّ. اختياريّ. استخدم هذا الخيار إذا كنت تريد البحث عن حدث باستخدام معرّف iالتقويم. |
maxAttendees |
integer |
الحد الأقصى لعدد الضيوف الذين سيتم تضمينهم في الرد. وإذا كان هناك أكثر من العدد المحدّد من الضيوف، يتم عرض المشارك فقط. اختياريّ. |
maxResults |
integer |
الحد الأقصى لعدد الأحداث التي يتم عرضها في صفحة نتائج واحدة. قد يكون عدد الأحداث في الصفحة الناتجة أقل من هذه القيمة أو قد لا يحدث على الإطلاق، حتى إذا كان هناك المزيد من الأحداث المتطابقة مع طلب البحث. يمكن رصد الصفحات غير المكتملة من خلال حقل nextPageToken غير فارغ في الردّ. وتكون القيمة 250 حدثًا تلقائيًا. لا يمكن أبدًا أن يتجاوز حجم الصفحة 2,500 حدث. اختياريّ.
|
orderBy |
string |
ترتيب الأحداث التي تم إرجاعها في النتيجة. اختياريّ. ويكون الترتيب التلقائي هو الترتيب الثابت غير المحدَّد.
القيم المقبولة هي:
|
pageToken |
string |
رمز مميّز يحدّد صفحة النتائج المطلوب عرضها اختياريّ. |
privateExtendedProperty |
string |
قيد الخصائص الموسعة محدد كالخاصية PropertyName=value. يطابق الممتلكات الخاصة فقط. يمكن تكرار هذه المَعلمة عدة مرات لعرض الأحداث التي تتطابق مع جميع القيود المحدّدة. |
q |
string |
عبارات البحث النصي المجاني للعثور على الأحداث التي تتطابق مع هذه العبارات في الحقول التالية:
وتتطابق عبارات البحث هذه أيضًا مع الكلمات الرئيسية المحدَّدة مسبقًا مع جميع ترجمات العنوان المعروض لمكان العمل، وخارج المكتب، وأحداث وقت التركيز. على سبيل المثال، يؤدي البحث عن "Office" أو "Bureau" إلى عرض أحداث العمل من النوع |
sharedExtendedProperty |
string |
قيد الخصائص الموسعة محدد كالخاصية PropertyName=value. يطابق المواقع المشتركة فقط. يمكن تكرار هذه المَعلمة عدة مرات لعرض الأحداث التي تتطابق مع جميع القيود المحدّدة. |
showDeleted |
boolean |
لتحديد ما إذا كان سيتم تضمين الأحداث المحذوفة (بحيث status يساوي "cancelled ") في النتيجة. سيتم تضمين الأحداث التي تم إلغاؤها من الأحداث المتكرّرة (وليس الحدث الأساسي المتكرّر) في حال ضبط كل من showDeleted وsingleEvents على "خطأ". إذا كان كل من showDeleted وsingleEvents "صحيح"، سيتم عرض أحداث فردية فقط من الأحداث المحذوفة (وليس الأحداث الأساسية المتكررة). اختياريّ. والقيمة التلقائية هي "خطأ".
|
showHiddenInvitations |
boolean |
ما إذا كان سيتم تضمين دعوات مخفية في النتيجة اختياريّ. والقيمة التلقائية هي "خطأ". |
singleEvents |
boolean |
تحديد ما إذا كان سيتم توسيع الأحداث المتكررة إلى مثيلات وعرض الأحداث لمرة واحدة وحالات الأحداث المتكررة فقط، ولكن ليس الأحداث المتكررة الأساسية نفسها اختياريّ. والقيمة التلقائية هي "خطأ". |
syncToken |
string |
تم عرض الرمز المميّز الذي تم الحصول عليه من الحقل nextSyncToken في الصفحة الأخيرة من نتائج طلب القائمة السابق. ويجعل نتيجة طلب القائمة هذا تحتوي فقط على الإدخالات التي تم تغييرها منذ ذلك الحين. سيتم حذف جميع الأحداث لأنّ طلب القائمة السابق سيكون دائمًا في مجموعة النتائج، ولا يُسمح بضبط showDeleted على "خطأ". هناك العديد من مَعلمات طلب البحث التي لا يمكن تحديدها مع nextSyncToken لضمان اتّساق حالة العميل. في ما يلي:
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 |
دور وصول المستخدم إلى هذا التقويم. للقراءة فقط القيم المتاحة:
|
|
defaultReminders[] |
list |
التذكيرات التلقائية في التقويم للمستخدم الذي تمت المصادقة عليه. تنطبق هذه التذكيرات على جميع الأحداث في هذا التقويم التي لا تلغيها بشكل صريح (أي لم يتم ضبط reminders.useDefault على "صحيح"). |
|
defaultReminders[].method |
string |
تمثّل هذه السمة الطريقة المستخدمة في هذا التذكير. القيم المتاحة:
مطلوبة عند إضافة تذكير. |
قابل للكتابة |
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?
تجربة
استخدِم مستكشف واجهات برمجة التطبيقات أدناه لطلب هذه الطريقة على البيانات المباشرة والاطّلاع على الردّ.