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
    }
  ]
}
اسم الموقع القيمة الوصف ملاحظات
timeMin datetime يشير ذلك المصطلح إلى بداية الفاصل الزمني لطلب البحث المنسَّق وفقًا لمعيار RFC3339.
timeMax datetime تمثّل هذه السمة نهاية الفاصل الزمني لطلب البحث المنسَّق وفقًا لمعيار RFC3339.
timeZone string المنطقة الزمنية المستخدَمة في الردّ اختياريّ. التوقيت التلقائي هو التوقيت العالمي المتفق عليه (UTC).
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
        }
      ]
    }
  }
}
اسم الموقع القيمة الوصف ملاحظات
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 نهاية الفترة الزمنية (حصرية)

جرّب الآن

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