Freebusy: query

لعرض معلومات الحالة متوفّر/مشغول لمجموعة من التقاويم. تجربة ذلك الآن

الطلب

طلب HTTP

POST https://www.googleapis.com/calendar/v3/freeBusy

التفويض

يسمح هذا الطلب بالتفويض باستخدام نطاق واحد على الأقل من النطاقات التالية:

النطاق
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar

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

نص الطلب

في نص الطلب، يمكنك توفير البيانات بالبنية التالية:

{
  "timeMin": datetime,
  "timeMax": datetime,
  "timeZone": string,
  "groupExpansionMax": integer,
  "calendarExpansionMax": integer,
  "items": [
    {
      "id": string
    }
  ]
}
اسم الموقع القيمة الوصف Notes
timeMin datetime بداية الفاصل الزمني لطلب البحث بتنسيق RFC3339.
timeMax datetime نهاية الفاصل الزمني لطلب البحث الذي تم تنسيقه وفق RFC3339.
timeZone string المنطقة الزمنية المستخدَمة في الردّ. اختياريّ. التوقيت التلقائي هو التوقيت العالمي المتفق عليه.
groupExpansionMax integer الحد الأقصى لعدد معرّفات التقويم التي يمكن تقديمها لمجموعة واحدة اختياريّ. يتم عرض خطأ لمجموعة تضم أعضاء أكثر من هذه القيمة. الحد الأقصى للقيمة هو 100.
calendarExpansionMax integer أقصى عدد من التقاويم التي سيتم تقديم معلومات FreeBusy لها. اختياريّ. الحد الأقصى للقيمة هو 50.
items[] list قائمة بالتقاويم و/أو المجموعات المطلوب البحث فيها
items[].id string معرِّف تقويم أو مجموعة.

الإجابة

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

{
  "kind": "calendar#freeBusy",
  "timeMin": datetime,
  "timeMax": datetime,
  "groups": {
    (key): {
      "errors": [
        {
          "domain": string,
          "reason": string
        }
      ],
      "calendars": [
        string
      ]
    }
  },
  "calendars": {
    (key): {
      "errors": [
        {
          "domain": string,
          "reason": string
        }
      ],
      "busy": [
        {
          "start": datetime,
          "end": datetime
        }
      ]
    }
  }
}
اسم الموقع القيمة الوصف Notes
kind string نوع المورد ("calendar#freeBusy").
timeMin datetime بداية الفاصل الزمني.
timeMax datetime نهاية الفاصل الزمني.
groups object توسيع المجموعات.
groups.(key) nested object قائمة بالتقاويم الأعضاء في هذه المجموعة
groups.(key).errors[] list أخطاء اختيارية (في حال تعذُّر إجراء العملية الحسابية للمجموعة).
groups.(key).errors[].domain string النطاق أو الفئة العامة للخطأ.
groups.(key).errors[].reason string السبب المحدد للخطأ. في ما يلي بعض القيم المحتمَلة:
  • "groupTooBig" - مجموعة المستخدمين المطلوبة كبيرة جدًا لطلب بحث واحد.
  • "tooManyCalendarsRequested" - عدد التقاويم المطلوبة كبير جدًا لطلب بحث واحد.
  • "notFound" - لم يتم العثور على المورد المطلوب.
  • "internalError" - حدث خطأ داخلي في خدمة واجهة برمجة التطبيقات.
قد تتم إضافة أنواع أخطاء أخرى في المستقبل، لكي يتعامل العملاء بشكلٍ ملائم مع حالات الخطأ الإضافية غير المدرَجة في هذه القائمة.
groups.(key).calendars[] list قائمة بمعرّفات التقاويم داخل مجموعة
calendars object قائمة بمعلومات الحالة متوفّر/مشغول للتقاويم.
calendars.(key) nested object توسيعات الحالة متوفّر/مشغول لتقويم واحد.
calendars.(key).errors[] list أخطاء اختيارية (في حال تعذُّر العملية الحسابية للتقويم).
calendars.(key).errors[].domain string النطاق أو الفئة العامة للخطأ.
calendars.(key).errors[].reason string السبب المحدد للخطأ. في ما يلي بعض القيم المحتمَلة:
  • "groupTooBig" - مجموعة المستخدمين المطلوبة كبيرة جدًا لطلب بحث واحد.
  • "tooManyCalendarsRequested" - عدد التقاويم المطلوبة كبير جدًا لطلب بحث واحد.
  • "notFound" - لم يتم العثور على المورد المطلوب.
  • "internalError" - حدث خطأ داخلي في خدمة واجهة برمجة التطبيقات.
قد تتم إضافة أنواع أخطاء أخرى في المستقبل، لكي يتعامل العملاء بشكلٍ ملائم مع حالات الخطأ الإضافية غير المدرَجة في هذه القائمة.
calendars.(key).busy[] list قائمة النطاقات الزمنية التي يجب اعتبار هذا التقويم خلالها مشغولاً.
calendars.(key).busy[].start datetime بداية (شاملة) الفترة الزمنية.
calendars.(key).busy[].end datetime نهاية الفترة الزمنية (حصرية).

تجربة

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