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

تغطّي حقول موارد الأحداث البيانات الأكثر شيوعًا المرتبطة بحدث معيّن، مثل الموقع الجغرافي ووقت البدء وما إلى ذلك، ولكن قد تحتاج التطبيقات إلى تخزين بيانات وصفية إضافية خاصة بحالة الاستخدام. توفّر 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

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

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

يُرجى العِلم أنّ القيود المفروضة على السمات الخاصة والمشترَكة يتم ربطها معًا باستخدام AND، لذا يجب أن تتطابق الأحداث مع مجموعتَي القيود ليتم عرضها. يعثر المثال التالي على الأحداث التي تتضمّن السمة الخاصة 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 خصائص مشتركة وخاصة، وذلك في جميع "نسخ" الحدث.