Halaman ini diterjemahkan oleh Cloud Translation API.

Kalender & acara

Panduan ini menjelaskan kalender, acara, dan hubungannya satu sama lain.

Kalender

Kalender adalah kumpulan peristiwa terkait, bersama dengan 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 rentang tanggal atau waktu tertentu. Peristiwa diidentifikasi dengan ID unik. Selain permulaan dan tanggal akhir-waktu, peristiwa 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. Acara dengan waktu gunakan kolom start.dateTime dan end.dateTime untuk menentukan kapan keduanya terjadi.
Acara sepanjang hari berlangsung sepanjang hari atau serangkaian hari berturut-turut. Sepanjang hari peristiwa menggunakan kolom start.date dan end.date untuk menentukan waktu terjadinya. Perhatikan bahwa kolom zona waktu tidak memiliki signifikansi untuk acara sepanjang hari.

Awal dan akhir acara harus memiliki waktu atau keduanya sepanjang hari. Misalnya, tidak valid untuk menentukan start.date dan end.dateTime.

Penyelenggara

Acara memiliki satu pengelola yang merupakan kalender yang berisi salinan utama acara tersebut. Acara juga dapat memiliki beberapa peserta. Tamu biasanya adalah kalender utama dari pengguna yang diundang.

Diagram berikut menunjukkan hubungan konseptual antar kalender, peristiwa, dan elemen terkait lainnya:

Kalender utama & kalender lainnya

Kalender utama adalah jenis kalender khusus yang terkait dengan satu menggunakan akun layanan. 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 dapat dihapus atau "tidak dimiliki" dengan . Namun, konten tersebut masih dapat dibagikan kepada pengguna lain.

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

Kalender & daftar kalender

Koleksi Kalender mewakili semua kalender yang ada. 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 default kalender zona waktu adalah properti global.

CalendarList adalah koleksi semua entri kalender yang telah ditambahkan pengguna ke daftarnya (ditampilkan di panel kiri UI web). Anda dapat menggunakannya untuk menambah dan menghapus yang sudah ada kalender ke/dari daftar pengguna. Anda juga bisa menggunakannya untuk mengambil nilai properti kalender khusus pengguna, seperti pengingat default. Lainnya contoh adalah warna latar depan, karena pengguna yang berbeda dapat memiliki warna yang berbeda 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 plus penyesuaian khusus pengguna seperti warna atau mengganti pengingat.
`patch`/`update`	Memodifikasi metadata kalender.	Memodifikasi properti kalender khusus pengguna.

Acara rutin

Beberapa acara terjadi beberapa kali dalam jadwal rutin, seperti pertemuan mingguan, ulang tahun, dan hari libur. Selain memiliki waktu mulai dan 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 hanya satu acara 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 string Properti RRULE, RDATE, atau EXDATE seperti yang ditentukan dalam RFC 5545.

Properti RRULE adalah yang paling penting karena menentukan aturan reguler untuk mengulangi acara. Elemen 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.

Anda dapat menggunakan COUNT atau CONTINUE untuk menentukan akhir dari pengulangan kejadian. Jangan gunakan keduanya dalam aturan yang sama.
UNTIL — Tanggal atau tanggal-waktu hingga peristiwa harus diulang (inklusif).
BYDAY — Hari 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 peristiwa yang seharusnya 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 kapan peristiwa tersebut tidak boleh terjadi. Artinya, kejadian-kejadian itu 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 satu yang dikecualikan oleh semua aturan EXDATE.

Berikut beberapa contoh peristiwa berulang:

Acara yang berlangsung dari pukul 06.00 hingga 07.00 setiap hari Selasa dan Jumat yang dimulai dari pukul 06.00 hingga 07.00 dari 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

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

Perubahan acara berulang dapat memengaruhi seluruh acara rutin (dan semua kejadiannya), atau hanya kejadian individual. Peristiwa yang berbeda dari acara rutin induknya disebut pengecualian.

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

Contoh cara menangani acara rutin dan kejadian 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 menetapkan 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 disajikan oleh events.get(), events.list(), dan Metode events.instances().

Konversi zona waktu hasil kueri: Hasil get(), list(), dan instances() ditampilkan dalam zona waktu yang Anda tentukan dalam timeZone . Jika Anda menghilangkan parameter ini, maka semua metode ini akan menggunakan jenis kalender zona waktu default.
Mencocokkan acara sepanjang hari dengan kueri berbatas waktu: list(), dan instances() memungkinkan Anda menetapkan 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 waktu berakhir acara sepanjang hari untuk menentukan apakah filter tersebut memenuhi spesifikasi filter.

Zona Waktu Acara

Instance peristiwa memiliki waktu mulai dan waktu berakhir; spesifikasi untuk waktu ini dapat menyertakan zona waktu. Anda dapat menentukan zona waktu dengan beberapa cara; tindakan berikut ini semua menentukan waktu yang sama:

Sertakan offset zona waktu di kolom dateTime, misalnya 2017-01-25T09:00:00-0500.
Tentukan waktu tanpa offset, misalnya 2017-01-25T09:00:00, membiarkan kolom timeZone kosong (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 adalah sama di semua kasus ini, tetapi menyetel kolom timeZone akan melampirkan zona waktu ke peristiwa, sama seperti saat Anda menyetel zona waktu acara menggunakan Kalender UI:

Zona waktu acara berulang

Untuk acara rutin, satu zona waktu harus selalu ditentukan. Ini diperlukan untuk memperluas pengulangan acara.