Panduan ini menjelaskan kalender, acara, dan hubungannya satu sama lain.
Kalender
Kalender adalah kumpulan acara terkait, beserta metadata tambahan seperti ringkasan, zona waktu default, lokasi, dll. Setiap kalender diidentifikasi dengan ID yang merupakan alamat email. Kalender dapat memiliki beberapa pemilik.
Acara
Peristiwa adalah objek yang terkait dengan tanggal atau rentang waktu tertentu. Peristiwa diidentifikasi dengan ID unik. Selain waktu tanggal mulai dan akhir, acara berisi data lain seperti ringkasan, deskripsi, lokasi, status, pengingat, lampiran, dll.
Jenis peristiwa
Google Kalender mendukung acara tunggal dan rutin:
- Satu peristiwa mewakili kejadian unik.
- Peristiwa rutin menentukan beberapa kejadian.
Acara juga dapat dijadwalkan atau sepanjang hari:
- Peristiwa timed terjadi di antara dua titik waktu tertentu. Peristiwa berjangka waktu menggunakan kolom
start.dateTime
danend.dateTime
untuk menentukan kapan peristiwa tersebut terjadi. - Acara sepanjang hari berlangsung sepanjang hari atau serangkaian hari berturut-turut. Peristiwa sepanjang hari menggunakan kolom
start.date
danend.date
untuk menentukan waktu terjadinya peristiwa tersebut. Perhatikan bahwa kolom zona waktu tidak memiliki signifikansi untuk acara sepanjang hari.
Penyelenggara
Acara memiliki satu pengelola, yaitu kalender yang berisi salinan utama acara. Acara juga dapat memiliki beberapa peserta. Tamu biasanya adalah kalender utama dari pengguna yang diundang.
Diagram berikut menunjukkan hubungan konseptual antara kalender, peristiwa, dan elemen terkait lainnya:
Kalender utama & kalender lainnya
Kalender utama adalah jenis kalender khusus yang terkait dengan satu akun pengguna. Kalender ini dibuat secara otomatis untuk setiap akun pengguna baru dan ID-nya biasanya cocok dengan alamat email utama pengguna. Selama akun ada, kalender utamanya tidak akan pernah bisa dihapus atau "tidak dimiliki" oleh pengguna. Namun, konten tersebut masih dapat dibagikan kepada pengguna lain.
Selain kalender utama, Anda dapat secara eksplisit membuat sejumlah kalender lain; kalender tersebut dapat diubah, dihapus, dan dibagikan dengan beberapa pengguna.
Kalender & daftar kalender
Koleksi Kalender mewakili semua kalender yang ada. Ini dapat digunakan untuk membuat dan menghapus kalender. Anda juga dapat mengambil atau menetapkan properti global yang dibagikan ke semua pengguna dengan akses ke kalender. Misalnya, judul kalender dan zona waktu default adalah properti global.
CalendarList adalah koleksi semua entri kalender yang telah ditambahkan pengguna ke daftar mereka (ditampilkan di panel kiri UI web). Anda bisa menggunakannya untuk menambah dan menghapus kalender yang ada ke/dari daftar pengguna. Anda juga menggunakannya untuk mengambil dan menetapkan nilai properti kalender khusus pengguna, seperti pengingat default. Contoh lain adalah warna latar depan, karena pengguna yang berbeda dapat memiliki warna berbeda yang ditetapkan untuk kalender yang sama.
Tabel berikut membandingkan arti operasi untuk kedua koleksi tersebut:
Operasi | Kalender | CalendarList |
---|---|---|
insert |
Membuat kalender sekunder baru. Secara default, kalender ini juga ditambahkan ke daftar kalender pembuat. | Menyisipkan kalender yang sudah ada ke daftar pengguna. |
delete |
Menghapus kalender sekunder. | Menghapus kalender dari daftar pengguna. |
get |
Mengambil metadata kalender, mis. judul, zona waktu. | Mengambil metadata ditambah penyesuaian khusus pengguna, seperti warna atau mengganti pengingat. |
patch /update |
Memodifikasi metadata kalender. | Memodifikasi properti kalender khusus pengguna. |
Acara rutin
Beberapa acara berlangsung beberapa kali dalam jadwal rutin, seperti rapat mingguan, ulang tahun, dan hari libur. Selain memiliki waktu mulai dan waktu berakhir yang berbeda, peristiwa berulang ini sering kali identik.
Acara disebut rutin jika berulang sesuai dengan jadwal yang ditentukan. Peristiwa tunggal tidak berulang dan hanya terjadi satu kali.
Aturan pengulangan
Jadwal untuk acara rutin didefinisikan dalam dua bagian:
Kolom awal dan akhir (yang menentukan kemunculan pertama, seolah-olah ini hanya merupakan peristiwa tunggal yang berdiri sendiri), dan
Kolom pengulangannya (yang menentukan bagaimana peristiwa harus diulang dari waktu ke waktu).
Kolom pengulangan berisi array string yang mewakili satu atau beberapa properti
RRULE
, RDATE
, atau EXDATE
seperti yang ditentukan dalam RFC
5545.
Properti RRULE
adalah yang paling penting karena menentukan aturan reguler untuk
mengulangi peristiwa. Elemen ini terdiri dari beberapa komponen. Beberapa di antaranya adalah:
FREQ
— Frekuensi pengulangan peristiwa (sepertiDAILY
atauWEEKLY
). Wajib.INTERVAL
— Berfungsi denganFREQ
untuk menentukan frekuensi pengulangan peristiwa. Misalnya,FREQ=DAILY;INTERVAL=2
berarti sekali setiap dua hari.COUNT
— Berapa kali peristiwa ini harus diulang.UNTIL
— Tanggal atau tanggal-waktu hingga peristiwa harus diulang (inklusif).BYDAY
— Hari saat peristiwa harus diulang (SU
,MO
,TU
, dll.). Komponen serupa lainnya mencakupBYMONTH
,BYYEARDAY
, danBYHOUR
.
Properti RDATE
menentukan tanggal atau tanggal-waktu tambahan saat peristiwa harus terjadi. Misalnya, RDATE;VALUE=DATE:19970101,19970120
.
Gunakan ini untuk menambahkan kemunculan tambahan yang tidak tercakup dalam RRULE
.
Properti EXDATE
mirip dengan RDATE, tetapi menentukan tanggal atau tanggal-waktu
saat peristiwa tidak boleh terjadi. Artinya, kejadian tersebut harus
dikecualikan. Alamat ini harus mengarah ke instance valid yang dibuat oleh aturan pengulangan.
EXDATE
dan RDATE
dapat memiliki zona waktu, dan harus berupa tanggal (bukan tanggal-waktu) untuk acara sepanjang hari.
Setiap properti dapat muncul dalam kolom pengulangan beberapa kali.
Pengulangan didefinisikan sebagai gabungan dari semua aturan RRULE
dan RDATE
, dikurangi yang dikecualikan oleh semua aturan EXDATE
.
Berikut beberapa contoh peristiwa berulang:
Peristiwa yang terjadi mulai pukul 06.00 hingga 07.00 setiap hari Selasa dan Jumat mulai 15 September 2015 dan berhenti setelah kejadian kelima pada 29 September:
... "start": { "dateTime": "2015-09-15T06:00:00+02:00", "timeZone": "Europe/Zurich" }, "end": { "dateTime": "2015-09-15T07:00:00+02:00", "timeZone": "Europe/Zurich" }, "recurrence": [ "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR" ], …
Acara sepanjang hari yang dimulai pada 1 Juni 2015 dan berulang setiap 3 hari sepanjang bulan, tidak termasuk 10 Juni tetapi termasuk 9 dan 11 Juni:
... "start": { "date": "2015-06-01" }, "end": { "date": "2015-06-02" }, "recurrence": [ "EXDATE;VALUE=DATE:20150610", "RDATE;VALUE=DATE:20150609,20150611", "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3" ], …
Instance & pengecualian
Peristiwa berulang terdiri dari beberapa instance: kejadian khususnya pada waktu yang berbeda. Instance ini berfungsi sebagai peristiwa itu sendiri.
Perubahan peristiwa berulang dapat memengaruhi seluruh peristiwa berulang (dan semua instance-nya), atau hanya instance individual. Peristiwa yang berbeda dari acara rutin induknya disebut pengecualian.
Misalnya, pengecualian mungkin memiliki ringkasan yang berbeda, waktu mulai yang berbeda, atau tamu tambahan yang diundang hanya ke instance tersebut. Anda juga dapat membatalkan
instance sepenuhnya tanpa menghapus peristiwa berulang
(pembatalan instance akan terlihat dalam peristiwa
status
).
Contoh cara menggunakan acara dan instance berulang melalui Google Calendar API dapat ditemukan di sini.
Zona waktu
Zona waktu menentukan wilayah yang menerapkan waktu standar yang seragam. Di Google Calendar API, Anda menentukan zona waktu menggunakan ID zona waktu IANA.
Anda dapat menyetel zona waktu untuk kalender dan acara. Bagian berikut menjelaskan pengaruh setelan ini.
Zona waktu kalender
Zona waktu kalender juga dikenal sebagai zona waktu default karena
implikasinya terhadap hasil kueri. Zona waktu kalender memengaruhi cara
nilai waktu ditafsirkan atau ditampilkan oleh
metode events.get()
,
events.list()
, dan
events.instances()
.
- Konversi zona waktu hasil kueri
- Hasil metode
get()
,list()
, daninstances()
ditampilkan dalam zona waktu yang Anda tentukan dalam parametertimeZone
. Jika Anda menghapus parameter ini, semua metode ini akan menggunakan zona waktu kalender sebagai default. - Mencocokkan acara sepanjang hari dengan kueri berbatas waktu
- Metode
list()
, daninstances()
memungkinkan Anda menentukan filter waktu mulai dan waktu berakhir, dengan metode yang menampilkan instance yang berada dalam rentang yang ditentukan. Zona waktu kalender digunakan untuk menghitung waktu mulai dan berakhir acara sepanjang hari untuk menentukan apakah waktu tersebut termasuk dalam spesifikasi filter.
Zona Waktu Acara
Instance peristiwa memiliki waktu mulai dan waktu berakhir; spesifikasi untuk waktu ini dapat mencakup zona waktu. Anda dapat menentukan zona waktu dengan beberapa cara; semuanya menentukan waktu yang sama:
- Sertakan offset zona waktu di kolom
dateTime
, misalnya2017-01-25T09:00:00-0500
. - Tentukan waktu tanpa offset, misalnya
2017-01-25T09:00:00
, membiarkan kolomtimeZone
kosong (secara implisit menggunakan zona waktu default). - Tentukan waktu tanpa offset, misalnya
2017-01-25T09:00:00
, tetapi gunakan kolomtimeZone
untuk menentukan zona waktu.
Anda juga dapat menentukan waktu acara dalam UTC jika mau:
- Tentukan waktu dalam UTC:
2017-01-25T14:00:00Z
atau gunakan offset nol2017-01-25T14:00:00+0000
.
Representasi internal waktu acara sama dalam semua kasus ini,
tetapi menetapkan kolom timeZone
akan melampirkan zona waktu ke acara, sama seperti
saat Anda menetapkan zona waktu acara menggunakan UI
Kalender:
Zona waktu acara berulang
Untuk acara rutin, satu zona waktu harus selalu ditentukan. Ini diperlukan untuk memperluas pengulangan acara.