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

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

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

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

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

พร็อพเพอร์ตี้ที่ขยายจะกำหนดไว้ในทรัพยากรเหตุการณ์ และคุณจะตั้งค่าพร็อพเพอร์ตี้แบบขยายในคำขอ insert, update และ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

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