Properti yang diperluas

Kolom resource Peristiwa mencakup data paling umum yang terkait dengan suatu peristiwa, seperti lokasi, waktu mulai, dll., tetapi aplikasi mungkin ingin menyimpan metadata tambahan yang khusus untuk kasus penggunaannya. Calendar API menyediakan kemampuan untuk menetapkan pasangan nilai kunci tersembunyi dengan suatu peristiwa, yang disebut properti diperluas. Properti diperluas memudahkan penyimpanan data khusus aplikasi untuk suatu peristiwa tanpa harus menggunakan database eksternal.

Visibilitas

Ada dua jenis properti diperluas yang tersedia: pribadi dan bersama. Properti bersama terlihat dan dapat diedit oleh semua peserta acara, sedangkan properti pribadi ditetapkan pada "salinan" acara lokal milik satu peserta. Secara lebih konkret, properti pribadi khusus untuk calendarId dan eventId yang digunakan dalam permintaan, sedangkan properti bersama akan ditampilkan terlepas dari calendarId yang digunakan dalam permintaan.

Menambahkan &memperbarui properti

Properti diperluas ditetapkan pada resource Peristiwa, dan seperti kolom lainnya, dapat ditetapkan dalam permintaan penyisipan, pembaruan, dan patch. Penggunaan permintaan patch adalah metode yang lebih disukai, karena memungkinkan Anda memanipulasi beberapa properti tanpa mengubah properti lainnya. Menambahkan properti baru dengan kunci yang sama akan menimpa properti yang ada dengan kunci yang sama. Contoh berikut menunjukkan cara menetapkan properti pribadi:

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

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

Menghapus properti

Properti apa pun yang tidak disertakan dalam permintaan pembaruan akan dihapus, tetapi pendekatan yang lebih baik adalah membuat permintaan patch untuk menetapkan nilai ke null. Contoh berikut menunjukkan cara menghapus properti pribadi:

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

{
  "extendedProperties": {
    "private": {
      "petsAllowed": null
    }
  }
}

Properti penelusuran

Anda dapat menelusuri peristiwa berdasarkan nilai pada properti diperluasnya menggunakan permintaan Events.list. Tetapkan kolom privateExtendedProperty atau sharedExtendedProperty ke batasan dalam format propertyName=value, yang masing-masing menelusuri properti pribadi dan bersama. Contoh berikut menampilkan peristiwa dengan properti pribadi petsAllowed=yes:

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

Anda dapat mengulangi kolom ini beberapa kali dan batasannya di-OR-kan bersama-sama, sehingga peristiwa hanya perlu cocok dengan salah satu batasan agar dapat ditampilkan. Contoh berikut menemukan peristiwa dengan properti pribadi petsAllowed=yes atau isOutside=yes:

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

Perlu diketahui bahwa batasan pada properti pribadi dan bersama di-AND-kan bersama-sama, sehingga peristiwa harus cocok dengan kedua kumpulan batasan agar dapat ditampilkan. Contoh berikut menemukan peristiwa dengan properti pribadi petsAllowed=yes dan properti publik createdBy=myApp:

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

Batas

1. Ukuran maksimum kunci properti adalah 44 karakter, dan properti dengan kunci yang lebih panjang akan dihilangkan tanpa pemberitahuan.
2. Ukuran maksimum nilai properti adalah 1024 karakter, dan properti dengan nilai yang lebih panjang akan dipangkas tanpa pemberitahuan.
3. Suatu peristiwa dapat memiliki hingga 300 properti dengan total ukuran hingga 32 kB (ukuran kunci + ukuran nilai). 300 properti ini mencakup properti bersama dan pribadi, di semua "salinan" peristiwa.