Kalender & acara

Panduan ini menjelaskan kalender, acara, dan hubungan antara keduanya.

Kalender

Kalender adalah kumpulan acara terkait, beserta metadata tambahan seperti ringkasan, zona waktu default, lokasi, dll. Setiap kalender diidentifikasi berdasarkan ID yang berupa alamat email. Kalender dapat memiliki beberapa pemilik.

Acara

Acara adalah objek yang terkait dengan rentang tanggal atau waktu tertentu. Peristiwa diidentifikasi oleh ID unik. Selain tanggal dan waktu mulai dan berakhir, acara berisi data lain seperti ringkasan, deskripsi, lokasi, status, pengingat, lampiran, dll.

Jenis peristiwa

Google Kalender mendukung acara tunggal dan berulang:

• Peristiwa tunggal mewakili kejadian unik.
• Acara berulang menentukan beberapa kemunculan.

Acara juga dapat dijadwalkan atau sepanjang hari:

• Peristiwa berjangka waktu terjadi di antara dua titik waktu tertentu. Peristiwa berjangka waktu menggunakan kolom start.dateTime dan end.dateTime untuk menentukan kapan peristiwa tersebut terjadi.
• Acara sepanjang hari berlangsung selama satu hari penuh atau serangkaian hari berturut-turut. Acara sepanjang hari menggunakan kolom start.date dan end.date untuk menentukan kapan acara tersebut terjadi. Perhatikan bahwa kolom zona waktu tidak memiliki arti untuk acara sepanjang hari.

Penyelenggara

Acara memiliki satu penyelenggara, yaitu kalender yang berisi salinan utama acara. Acara juga dapat memiliki beberapa tamu. Tamu biasanya adalah kalender utama pengguna yang diundang.

Diagram berikut menunjukkan hubungan konseptual antara kalender, acara, 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 dapat dihapus atau "dibatalkan kepemilikannya" oleh pengguna. Namun, file tersebut masih dapat dibagikan kepada pengguna lain.

Selain kalender utama, Anda dapat membuat sejumlah kalender lain secara eksplisit; kalender ini dapat diubah, dihapus, dan dibagikan di antara beberapa pengguna.

Kalender & daftar kalender

Koleksi Calendars mewakili semua kalender yang ada. API ini dapat digunakan untuk membuat dan menghapus kalender. Anda juga dapat mengambil atau menetapkan properti global yang dibagikan di semua pengguna yang memiliki akses ke kalender. Misalnya, judul dan zona waktu default kalender adalah properti global.

CalendarList adalah kumpulan semua entri kalender yang telah ditambahkan pengguna ke daftarnya (ditampilkan di panel kiri UI web). Anda dapat menggunakannya untuk menambahkan 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 lainnya adalah warna latar depan, karena pengguna yang berbeda dapat menetapkan warna yang berbeda untuk kalender yang sama.

Tabel berikut membandingkan arti operasi untuk kedua koleksi:

Operasi	Kalender	CalendarList
insert	Membuat kalender sekunder baru. Secara default, kalender ini juga ditambahkan ke daftar kalender kreator.	Menyisipkan kalender yang ada ke dalam daftar pengguna.
delete	Menghapus kalender sekunder.	Menghapus kalender dari daftar pengguna.
get	Mengambil metadata kalender, misalnya judul, zona waktu.	Mengambil metadata plus penyesuaian khusus pengguna seperti warna atau penggantian pengingat.
patch/update	Mengubah metadata kalender.	Mengubah properti kalender khusus pengguna.

Acara berulang

Beberapa acara terjadi beberapa kali dalam jadwal rutin, seperti rapat mingguan, ulang tahun, dan hari libur. Selain memiliki waktu mulai dan berakhir yang berbeda, acara berulang ini sering kali identik.

Acara disebut berulang jika diulang sesuai dengan jadwal yang ditentukan. Acara tunggal tidak berulang dan hanya terjadi satu kali.

Aturan pengulangan

Jadwal untuk acara berulang ditentukan dalam dua bagian:

• Kolom start dan end-nya (yang menentukan kemunculan pertama, seolah-olah ini hanya satu peristiwa mandiri), dan

• Kolom pengulangannya (yang menentukan cara pengulangan acara dari waktu ke waktu).

Kolom pengulangan berisi array string yang merepresentasikan satu atau beberapa properti RRULE, RDATE, atau EXDATE sebagaimana ditentukan dalam RFC 5545.

Properti RRULE adalah yang paling penting karena menentukan aturan reguler untuk mengulangi peristiwa. Aplikasi ini terdiri dari beberapa komponen. Beberapa di antaranya adalah:

• FREQ — Frekuensi pengulangan peristiwa (seperti DAILY atau WEEKLY). Wajib diisi.

• INTERVAL — Bekerja sama dengan FREQ untuk menentukan seberapa sering acara harus diulang. Misalnya, FREQ=DAILY;INTERVAL=2 berarti sekali setiap dua hari.

• COUNT — Berapa kali peristiwa ini harus diulang.

• UNTIL — Tanggal atau tanggal-waktu hingga acara harus diulang (inklusif).

• BYDAY — Hari dalam seminggu saat acara harus diulang (SU, MO, TU, dll.). Komponen serupa lainnya mencakup BYMONTH, BYYEARDAY, dan BYHOUR.

Properti RDATE menentukan tanggal atau tanggal-waktu tambahan saat kemunculan peristiwa harus terjadi. Misalnya, RDATE;VALUE=DATE:19970101,19970120. Gunakan ini untuk menambahkan kemunculan tambahan yang tidak tercakup oleh RRULE.

Properti EXDATE mirip dengan RDATE, tetapi menentukan tanggal atau tanggal dan waktu saat acara tidak boleh terjadi. Artinya, kejadian tersebut harus dikecualikan. Ini harus mengarah ke instance valid yang dihasilkan 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 ditentukan sebagai gabungan semua aturan RRULE dan RDATE, dikurangi aturan yang dikecualikan oleh semua aturan EXDATE.

Berikut beberapa contoh acara berulang:

1. Acara yang berlangsung dari 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"
   ],
   …
   

2. 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

Acara berulang terdiri dari beberapa instance: kejadian tertentu pada waktu yang berbeda. Instance ini bertindak sebagai peristiwa itu sendiri.

Perubahan acara berulang dapat memengaruhi seluruh acara berulang (dan semua instance-nya), atau hanya instance individual. Instans yang berbeda dari acara berulang induknya disebut pengecualian.

Misalnya, pengecualian dapat memiliki ringkasan yang berbeda, waktu mulai yang berbeda, atau tamu tambahan yang diundang hanya ke instance tersebut. Anda juga dapat membatalkan semua instance tanpa menghapus acara berulang (pembatalan instance tercermin dalam acara status).

Contoh cara menggunakan peristiwa 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 efek 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 dari metode get(), list(), dan instances() ditampilkan dalam zona waktu yang Anda tentukan dalam parameter timeZone. Jika Anda menghapus parameter ini, semua metode ini akan menggunakan zona waktu kalender sebagai default.

Mencocokkan acara sepanjang hari dengan kueri yang dibatasi waktu

Metode list(), dan instances() memungkinkan Anda menentukan filter waktu mulai dan akhir, dengan metode yang menampilkan instance yang termasuk dalam rentang yang ditentukan. Zona waktu kalender digunakan untuk menghitung waktu mulai dan akhir acara sepanjang hari untuk menentukan apakah acara tersebut termasuk dalam spesifikasi filter.

Zona Waktu Acara

Instance acara memiliki waktu mulai dan berakhir; spesifikasi untuk waktu ini dapat mencakup zona waktu. Anda dapat menentukan zona waktu dengan beberapa cara; berikut ini semuanya menentukan waktu yang sama:

• Sertakan selisih zona waktu di kolom dateTime, misalnya 2017-01-25T09:00:00-0500.
• Tentukan waktu tanpa offset, misalnya 2017-01-25T09:00:00, dengan mengosongkan kolom timeZone (ini secara implisit menggunakan zona waktu default).
• Tentukan waktu tanpa offset, misalnya 2017-01-25T09:00:00, tetapi gunakan kolom timeZone 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 nol 2017-01-25T14:00:00+0000.

Representasi internal waktu acara sama dalam semua kasus ini, tetapi menyetel kolom timeZone akan melampirkan zona waktu ke acara, sama seperti saat Anda menyetel zona waktu acara menggunakan UI Kalender:

Zona waktu acara berulang

Untuk acara berulang, satu zona waktu harus selalu ditentukan. ID ini diperlukan untuk memperluas pengulangan acara.