تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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?

جرّب الآن

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