المواقع الموسَّعة

تتناول حقول مراجع الأحداث البيانات الأكثر شيوعًا المرتبطة بأحد الأحداث، مثل الموقع الجغرافي ووقت البدء وما إلى ذلك، ولكن قد تحتاج التطبيقات إلى تخزين بيانات وصفية إضافية خاصة بحالة الاستخدام. توفّر واجهة برمجة التطبيقات Calendar API إمكانية تحديد أزواج مفاتيح وقيم مخفية مع حدث، تُعرف باسم السمات الموسّعة. تسهّل السمات الموسّعة تخزين البيانات الخاصة بالتطبيق لحدث معيّن بدون الحاجة إلى استخدام قاعدة بيانات خارجية.

مستوى الرؤية

يتوفّر نوعان من المواقع الإضافية: خاصة ومشترَكة. تكون السمات المشتركة مرئية وقابلة للتعديل من قِبل جميع الضيوف في الحدث، في حين يتم ضبط السمات الخاصة على "نسخة" محلية للضيف من الحدث. بعبارة أدق، تكون الخصائص الخاصة مرتبطة بكل من calendarId وeventId المستخدَمَين في الطلب، في حين سيتم عرض الخصائص المشتركة بغض النظر عن calendarId المستخدَم في الطلب.

إضافة المواقع وتحديثها

يتمّ ضبط السمات الموسّعة في مورد "الأحداث"، ويمكن، مثل الحقول الأخرى، ضبطها في طلبات الإدراج و التحديث و تصحيح الأخطاء. إنّ استخدام طلبات التعديل هو الأسلوب المفضّل، لأنّه يسمح لك بتعديل بعض السمات مع إبقاء سمات أخرى بدون تعديل. ستؤدي إضافة موقع جديد باستخدام المفتاح نفسه إلى استبدال أي مواقع حالية بالمفتاح نفسه. يوضّح المثال التالي كيفية ضبط خاصية خاصة:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": "yes"
    }
  }
}

حذف المواقع

سيتم حذف أيّ خصائص غير مضمّنة في طلب التعديل، ولكن من الأفضل اتّباع نهج أفضل وهو تقديم طلب تصحيح لضبط القيمة على "قيمة فارغة". يوضّح المثال التالي كيفية حذف موقع خاص:

PATCH https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

خصائص البحث

يمكنك البحث في الأحداث استنادًا إلى القيم في السمات الموسّعة باستخدام طلب Events.list. اضبط الحقل privateExtendedProperty أو sharedExtendedProperty على قيد بالتنسيق propertyName=value، الذي يبحث في المواقع الخاصة والمشترَكة على التوالي. يعرض المثال التالي الأحداث التي تحتوي على السمة الخاصة petsAllowed=yes:

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes

يمكنك تكرار هذه الحقول عدة مرات ويتم تجميع القيود معًا باستخدام "أو"، لذا ما عليك سوى أن تتطابق الأحداث مع أحد القيود لعرضها. يعثر المثال التالي على الأحداث التي تحتوي على السمة الخاصة petsAllowed=yes أو isOutside=yes:

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &privateExtendedProperty=isOutside%3Dyes

يُرجى العِلم أنّ قيود السمات الخاصة والمشترَكة يتم ربطها معًا باستخدام "و"، وبالتالي يجب أن تتطابق الأحداث مع كلتا مجموعتَي القيود لكي يتم عرضها. يعثر المثال التالي على الأحداث التي تتضمّن السمة الخاصة petsAllowed=yes والسمة العامة createdBy=myApp:

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events
    ?privateExtendedProperty=petsAllowed%3Dyes
    &sharedExtendedProperty=createdBy%3DmyApp

الحدود

1. الحد الأقصى لحجم مفتاح الموقع هو 44 حرفًا، وسيتم حذف المواقع التي تحتوي على مفاتيح أطول بدون إشعار.
2. الحد الأقصى لحجم قيمة السمة هو 1024 حرفًا، وسيتم اقتطاع السمات التي تحتوي على قيم أطول بدون إشعار.
3. يمكن أن يحتوي الحدث على 300 خاصيّة كحدّ أقصى بحجم إجمالي يصل إلى 32 كيلوبايت (حجم المفاتيح + حجم القيم). وتشمل هذه المواقع الـ 300 المواقع المشترَكة والمواقع الخاصة، في جميع "النُسخ" من الحدث.