คุณสมบัติเพิ่มเติม

ฟิลด์ของแหล่งข้อมูลเหตุการณ์ ครอบคลุมข้อมูลที่พบบ่อยที่สุดซึ่งเชื่อมโยงกับ เหตุการณ์ เช่น สถานที่ เวลาเริ่มต้น ฯลฯ แต่แอปพลิเคชันอาจต้องการจัดเก็บ ข้อมูลเมตาเพิ่มเติมที่เฉพาะเจาะจงสำหรับกรณีการใช้งานของตน Calendar API มีความสามารถในการตั้งค่าคู่คีย์-ค่าที่ซ่อนไว้กับเหตุการณ์ ซึ่งเรียกว่าพร็อพเพอร์ตี้แบบขยาย พร็อพเพอร์ตี้เพิ่มเติมช่วยให้จัดเก็บข้อมูลเฉพาะแอปพลิเคชันสำหรับเหตุการณ์ได้ง่าย โดยไม่ต้องใช้ฐานข้อมูลภายนอก

ระดับการแชร์

พร็อพเพอร์ตี้แบบขยายมี 2 ประเภท ได้แก่ แบบส่วนตัวและแบบแชร์ ผู้เข้าร่วมกิจกรรมทุกคนจะดูและแก้ไขพร็อพเพอร์ตี้ที่แชร์ได้ ส่วนพร็อพเพอร์ตี้ส่วนตัวจะตั้งค่าใน "สำเนา" ของกิจกรรมในเครื่องของผู้เข้าร่วมคนใดคนหนึ่ง กล่าวอย่างเจาะจงคือ พร็อพเพอร์ตี้ส่วนตัวจะเฉพาะเจาะจงกับ calendarId และ eventId ที่ใช้ในคำขอ ในขณะที่พร็อพเพอร์ตี้ที่แชร์จะแสดงโดยไม่คำนึงถึง calendarId ที่ใช้ในคำขอ

เพิ่มและอัปเดตที่พัก

พร็อพเพอร์ตี้เพิ่มเติมจะตั้งค่าในทรัพยากรเหตุการณ์ และตั้งค่าในคำขอ insert, update และ patch ได้เหมือนกับช่องอื่นๆ เราขอแนะนำให้ใช้คำขอ PATCH เนื่องจากช่วยให้คุณแก้ไขพร็อพเพอร์ตี้บางรายการได้โดยไม่ต้องแตะต้องพร็อพเพอร์ตี้อื่นๆ การเพิ่มพร็อพเพอร์ตี้ใหม่ที่มีคีย์เดียวกันจะเขียนทับพร็อพเพอร์ตี้ที่มีอยู่ ซึ่งมีคีย์เดียวกัน ตัวอย่างต่อไปนี้แสดงการตั้งค่าพร็อพเพอร์ตี้ส่วนตัว

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

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

ลบพร็อพเพอร์ตี้

ระบบจะลบพร็อพเพอร์ตี้ที่ไม่ได้รวมอยู่ในคำขออัปเดตออก แต่แนวทางที่ดีกว่าคือการส่งคำขอแพตช์เพื่อตั้งค่าเป็น Null ตัวอย่างต่อไปนี้แสดงการลบพร็อพเพอร์ตี้ส่วนตัว

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

โปรดทราบว่าข้อจํากัดในพร็อพเพอร์ตี้ส่วนตัวและพร็อพเพอร์ตี้ที่แชร์จะรวมกัน ดังนั้นเหตุการณ์ต้องตรงกับข้อจํากัดทั้ง 2 ชุดจึงจะแสดงได้ ตัวอย่างต่อไปนี้ค้นหากิจกรรมที่มีพร็อพเพอร์ตี้ส่วนตัว petsAllowed=yes และพร็อพเพอร์ตี้สาธารณะ createdBy=myApp

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

จำกัดสูงสุด

1. ขนาดสูงสุดของคีย์ของพร็อพเพอร์ตี้คือ 44 อักขระ และระบบจะทิ้งพร็อพเพอร์ตี้ที่มีคีย์ยาวกว่านี้โดยไม่มีการแจ้งเตือน
2. ค่าของพร็อพเพอร์ตี้มีขนาดสูงสุด 1, 024 อักขระ และพร็อพเพอร์ตี้ที่มีค่า ยาวกว่านี้จะถูกตัดให้สั้นลงโดยไม่มีการแจ้งเตือน
3. เหตุการณ์หนึ่งๆ มีพร็อพเพอร์ตี้ได้สูงสุด 300 รายการ โดยมีขนาดรวมสูงสุด 32 กิโลไบต์ (ขนาดคีย์ + ขนาดค่า) พร็อพเพอร์ตี้ 300 รายการนี้รวมถึงพร็อพเพอร์ตี้ที่แชร์และพร็อพเพอร์ตี้ส่วนตัวใน "สำเนา" ทั้งหมดของเหตุการณ์