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

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