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

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

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

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

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

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

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

โปรดทราบว่าข้อจำกัดในพร็อพเพอร์ตี้ส่วนตัวและพร็อพเพอร์ตี้ที่แชร์จะรวมกันแบบ AND ดังนั้นเหตุการณ์ต้องตรงกับข้อจำกัดทั้ง 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 KB (ขนาดคีย์ + ขนาดค่า) พร็อพเพอร์ตี้ 300 รายการนี้รวมถึงพร็อพเพอร์ตี้ที่แชร์และพร็อพเพอร์ตี้ส่วนตัวใน "สำเนา" ทั้งหมดของกิจกรรม