Properti yang diperluas

Kolom resource Acara mencakup data paling umum yang terkait dengan acara, seperti lokasi dan waktu mulai, tetapi aplikasi mungkin perlu menyimpan metadata tambahan yang khusus untuk kasus penggunaannya. Google Calendar API memungkinkan Anda menetapkan pasangan nilai kunci tersembunyi dengan acara, yang disebut properti yang diperluas. Properti yang diperluas memudahkan penyimpanan data khusus aplikasi untuk suatu peristiwa tanpa menggunakan database eksternal.

Visibilitas

Ada dua jenis properti tambahan yang tersedia: pribadi dan bersama. Properti bersama dapat dilihat dan diedit oleh semua peserta acara, sedangkan properti pribadi disetel di salinan lokal acara milik satu peserta. Lebih konkretnya, properti pribadi khusus untuk calendarId dan eventId yang digunakan dalam permintaan, sedangkan properti bersama muncul terlepas dari calendarId yang digunakan dalam permintaan.

Menambahkan dan memperbarui properti

Properti yang diperluas ditetapkan pada resource Events, dan seperti kolom lainnya, dapat ditetapkan dalam permintaan events.insert, events.update, dan events.patch. Penggunaan permintaan patch adalah metode yang lebih disukai, karena memungkinkan Anda memanipulasi beberapa properti dan tidak mengubah properti lainnya. Menambahkan properti baru dengan kunci yang sama akan menggantikan properti yang ada dengan kunci tersebut. Contoh berikut menunjukkan cara menyetel properti pribadi:

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

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

Menghapus properti

Semua properti yang tidak disertakan dalam permintaan pembaruan akan dihapus, tetapi pendekatan yang lebih baik adalah membuat permintaan patch untuk menyetel nilai ke null. Contoh berikut menunjukkan penghapusan properti pribadi:

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

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

Telusuri properti

Anda dapat menelusuri peristiwa berdasarkan nilai properti yang diperluas menggunakan permintaan events.list. Tetapkan kolom privateExtendedProperty atau sharedExtendedProperty ke batasan dalam format propertyName=value, yang 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 batasan dievaluasi dengan logika OR, sehingga peristiwa hanya perlu cocok dengan salah satu batasan agar 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

Batasan pada properti pribadi dan bersama dievaluasi dengan logika AND, sehingga peristiwa harus cocok dengan kedua set 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; properti dengan kunci yang lebih panjang akan dihilangkan tanpa pemberitahuan.
2. Ukuran maksimum nilai properti adalah 1024 karakter; properti dengan nilai yang lebih panjang akan dipangkas tanpa pemberitahuan.
3. Peristiwa dapat memiliki hingga 300 properti dengan total ukuran hingga 32 KB (ukuran kunci ditambah ukuran nilai). 300 properti ini mencakup properti bersama dan pribadi di semua salinan peristiwa.