تمت ترجمة هذه الصفحة بواسطة 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`	أنواع الأحداث المطلوب عرضها. اختيارية: يمكن تكرار هذه المَعلمة عدة مرات لعرض أحداث من أنواع مختلفة. في حال عدم ضبطها، تعرض جميع أنواع الأحداث. القيم المقبولة هي: "`birthday`": أحداث خاصة تستمر ليوم كامل وتتكرّر سنويًا. "`default`": الأحداث المنتظمة ‫"`focusTime`": أحداث وقت التركيز "`fromGmail`": الأحداث من Gmail "`outOfOffice`": أحداث خارج المكتب ‫"`workingLocation`": أحداث مكان العمل
`iCalUID`	`string`	تحدّد هذه السمة رقم تعريف حدث بتنسيق iCalendar سيتم توفيره في الردّ. اختيارية: استخدِم هذا الخيار إذا كنت تريد البحث عن حدث باستخدام معرّف iCalendar الخاص به.
`maxAttendees`	`integer`	الحدّ الأقصى لعدد الضيوف الذين سيتم تضمينهم في الردّ إذا كان هناك عدد أكبر من الضيوف المحدّدين، سيتم عرض المشارك فقط. اختيارية:
`maxResults`	`integer`	الحدّ الأقصى لعدد الأحداث المعروضة في صفحة نتائج واحدة قد يكون عدد الأحداث في الصفحة الناتجة أقل من هذه القيمة، أو قد لا يكون هناك أي أحداث على الإطلاق، حتى إذا كانت هناك أحداث أخرى تطابق طلب البحث. يمكن رصد الصفحات غير المكتملة من خلال الحقل `nextPageToken` غير الفارغ في الردّ. القيمة التلقائية هي 250 حدثًا. لا يمكن أن يتجاوز حجم الصفحة 2500 حدث. اختيارية:
`orderBy`	`string`	ترتيب الأحداث التي تم عرضها في النتيجة اختيارية: الترتيب التلقائي هو ترتيب ثابت غير محدّد. القيم المقبولة هي: استبدِل "`startTime`" بما يلي: الترتيب حسب تاريخ/وقت البدء (تصاعديًا). لا يتوفّر ذلك إلا عند البحث عن أحداث فردية (أي أنّ المَعلمة `singleEvents` تكون True). ‫"`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` False. إذا كانت قيمة كل من `showDeleted` و`singleEvents` هي True، لن يتم عرض سوى مثيلات فردية للأحداث المحذوفة (وليس الأحداث المتكررة الأساسية). اختيارية: القيمة التلقائية هي 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`
`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`": لدى المستخدم إذن وصول إداري إلى التقويم. يتمتع هذا الدور بجميع أذونات دور "الكاتب" مع إمكانية إضافية تتمثّل في الاطّلاع على مستويات وصول المستخدمين الآخرين وتعديلها. ملاحظة مهمة: يختلف دور `owner` عن مالك بيانات التقويم. يتضمّن التقويم مالك بيانات واحدًا، ولكن يمكن أن يتضمّن عدة مستخدمين لديهم دور `owner`.
`defaultReminders[]`	`list`	التذكيرات التلقائية في التقويم للمستخدم الذي تمّت مصادقته تنطبق هذه التذكيرات على جميع الأحداث في هذا التقويم التي لا تتجاوزها بشكل صريح (أي التي لم يتم ضبط `reminders.useDefault` على "صحيح").
`defaultReminders[].method`	`string`	الطريقة التي يستخدمها هذا التذكير. القيم المحتمَلة هي: `email`: يتم إرسال التذكيرات عبر البريد الإلكتروني. "`popup`": يتم إرسال التذكيرات من خلال نافذة منبثقة في واجهة المستخدم. يجب توفيرها عند إضافة تذكير.	قابل للكتابة
`defaultReminders[].minutes`	`integer`	عدد الدقائق قبل بدء الحدث عندما يجب أن يتم تشغيل التذكير. تتراوح القيم الصالحة بين 0 و40320 (4 أسابيع بالدقائق). يجب توفيرها عند إضافة تذكير.	قابل للكتابة
`nextPageToken`	`string`	الرمز المميز المستخدَم للوصول إلى الصفحة التالية من هذه النتيجة يتم حذفها في حال عدم توفّر نتائج إضافية، وفي هذه الحالة يتم تقديم `nextSyncToken`.
`items[]`	`list`	قائمة بالأحداث في التقويم
`nextSyncToken`	`string`	الرمز المميز المستخدَم في وقت لاحق لاسترداد الإدخالات التي تم تغييرها فقط منذ عرض هذه النتيجة يتم حذفها إذا كانت تتوفّر نتائج إضافية، وفي هذه الحالة يتم تقديم `nextPageToken`.

جرِّبها الآن.

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