Freebusy: query

تعرِض هذه الدالة معلومات الحالة "متوفّر" أو "مشغول" لمجموعة من التقاويم. جرِّب ذلك الآن.

الطلب

طلب HTTP

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

التفويض

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

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

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

نص الطلب

في نص الطلب، قدِّم البيانات بالبنية التالية:

{
  "timeMin": datetime,
  "timeMax": datetime,
  "timeZone": string,
  "groupExpansionMax": integer,
  "calendarExpansionMax": integer,
  "items": [
    {
      "id": string
    }
  ]
}
اسم السمة القيمة الوصف ملاحظات
timeMin datetime بداية الفاصل الزمني للطلب بتنسيق RFC3339.
timeMax datetime نهاية الفاصل الزمني لطلب البحث بتنسيق RFC3339
timeZone string المنطقة الزمنية المستخدَمة في الردّ اختياريّ. الإعداد التلقائي هو التوقيت العالمي المنسّق.
groupExpansionMax integer الحد الأقصى لعدد معرّفات التقاويم التي يجب تقديمها لمجموعة واحدة اختياريّ. يتم عرض خطأ في المجموعة التي تضم عددًا من الأعضاء أكبر من هذه القيمة. الحد الأقصى للقيمة هو 100.
calendarExpansionMax integer الحد الأقصى لعدد التقاويم التي يجب تقديم معلومات الحالة "متوفّر/مشغول" لها. اختياريّ. الحد الأقصى للقيمة هو 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
        }
      ]
    }
  }
}
اسم السمة القيمة الوصف ملاحظات
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 نهاية الفترة الزمنية (الحصرية).

جرّب الآن

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