Mengelola waktu fokus, tidak di kantor, dan acara lokasi kerja

Halaman ini menjelaskan cara menggunakan Google Calendar API untuk membuat acara yang menampilkan status pengguna Google Kalender. Peristiwa status menjelaskan di mana pengguna berada atau apa yang mereka lakukan, termasuk apakah mereka sedang berada di waktu fokus, tidak di kantor, atau bekerja dari lokasi tertentu.

Di Google Kalender, pengguna dapat membuat acara waktu fokus, tidak di kantor, dan lokasi kerja untuk menunjukkan status dan lokasi kustom mereka. Fitur ini hanya tersedia di kalender utama, dan untuk beberapa pengguna Google Kalender.

Untuk mengetahui detail selengkapnya, buka Menggunakan waktu fokus di Google Kalender dan Mengaktifkan atau menonaktifkan lokasi kerja untuk pengguna.

Membaca dan mencantumkan peristiwa status Kalender

Anda dapat membaca dan mencantumkan peristiwa status Kalender di resource Events Calendar API.

Untuk membaca peristiwa status, gunakan metode events.get, dengan menentukan eventId peristiwa.

Untuk mencantumkan peristiwa status, gunakan metode events.list, yang menentukan satu atau beberapa nilai berikut di kolom eventTypes:

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

Kemudian, dalam objek Event yang ditampilkan, periksa apakah kolom eventType memiliki nilai yang diminta, dan lihat kolom yang sesuai untuk mengetahui detail tentang status yang dibuat oleh pengguna di Google Kalender:

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

Berlangganan perubahan pada peristiwa status

Anda dapat berlangganan perubahan pada peristiwa status di resource Events Calendar API.

Gunakan metode events.watch, yang menentukan calendarId Kalender yang akan diikuti dan satu atau beberapa nilai berikut di kolom eventTypes:

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

Membuat dan memperbarui peristiwa status Kalender

Untuk membuat peristiwa status, buat instance resource Events menggunakan metode events.insert, yang menetapkan kolom wajib untuk jenis peristiwa tersebut.

Jika Anda memperbarui peristiwa status menggunakan metode events.update, peristiwa tersebut harus mempertahankan kolom yang diperlukan.

Membuat waktu fokus

Untuk membuat peristiwa waktu fokus:

• Tetapkan eventType ke 'focusTime'.
• Sertakan kolom focusTimeProperties.
• Tetapkan kolom transparency ke 'opaque'.
• Tetapkan kolom start dan end peristiwa menjadi peristiwa berwaktu (dengan waktu mulai dan berakhir yang ditentukan).
  Waktu fokus tidak boleh berupa acara sepanjang hari.

Untuk mengetahui detail fitur, buka Menggunakan waktu fokus di Google Kalender

Membuat status tidak di kantor

Untuk membuat acara tidak di kantor:

• Tetapkan eventType ke 'outOfOffice'.
• Sertakan kolom outOfOfficeProperties.
• Tetapkan kolom transparency ke 'opaque'.
• Menetapkan kolom start dan end peristiwa menjadi peristiwa terjadwal (dengan waktu mulai dan waktu berakhir yang ditentukan).
  Acara tidak di kantor tidak boleh berupa acara sepanjang hari.

Untuk mengetahui detail fitur, buka Tampilkan saat Anda tidak di kantor

Membuat lokasi kerja

Untuk membuat peristiwa lokasi kerja:

• Tetapkan eventType ke 'workingLocation'.
• Sertakan kolom workingLocationProperties.
• Tetapkan kolom visibility ke 'public'.
• Tetapkan kolom transparency ke 'transparent'.

• Tetapkan kolom start dan end peristiwa menjadi:

  • Acara berjangka waktu (dengan waktu mulai dan berakhir yang ditentukan);
  • Acara sepanjang hari (dengan tanggal mulai dan akhir yang ditentukan) yang berlangsung tepat satu hari.

  Acara lokasi kerja sepanjang hari tidak dapat berlangsung selama beberapa hari, tetapi acara dengan waktu dapat.

Kolom berikut bersifat opsional, tetapi direkomendasikan untuk pengalaman pengguna terbaik saat menyisipkan officeLocation:

• workingLocationProperties.officeLocation.buildingId: Ini harus cocok dengan buildingId dalam database resource organisasi. Hal ini membantu pengguna mendapatkan manfaat dari semua fitur Kalender, misalnya saran ruangan.
• workingLocationProperties.officeLocation.label: Ini adalah label yang ditampilkan di Kalender Web dan klien seluler. Anda dapat mengambil ID bangunan dan label bangunan menggunakan metode resources.buildings.list.

Membuat dan memperbarui peristiwa lokasi kerja melalui endpoint batch tidak didukung.

Untuk mengetahui detail fitur, buka Menetapkan jam kerja & lokasi dan Mengaktifkan atau menonaktifkan lokasi kerja untuk pengguna

Cara menampilkan peristiwa lokasi kerja yang tumpang-tindih

Pengguna dapat memiliki beberapa acara lokasi kerja di kalendernya secara bersamaan yang tumpang-tindih, yang berarti waktu tertentu dapat memiliki beberapa lokasi kerja yang ditetapkan untuk waktu tertentu. Dalam situasi saat hanya satu lokasi yang dapat ditampilkan kepada pengguna, mereka harus melihat lokasi tersebut secara konsisten di beberapa aplikasi. Saat melakukannya, gunakan panduan berikut untuk memilih peristiwa yang akan ditampilkan:

• Acara berjangka waktu lebih diprioritaskan daripada acara sepanjang hari.
• Peristiwa tunggal lebih diprioritaskan daripada peristiwa berulang dan pengecualian-nya.
• Peristiwa yang dimulai nanti akan lebih diutamakan daripada peristiwa yang dimulai lebih awal.
• Peristiwa dengan durasi yang lebih singkat lebih diutamakan daripada peristiwa dengan durasi yang lebih lama.
• Peristiwa yang dibuat lebih baru lebih diutamakan daripada peristiwa yang dibuat sebelumnya.
• Peristiwa yang tumpang-tindih sebagian harus ditampilkan sebagai dua peristiwa berbeda, masing-masing dengan lokasi kerja sendiri.

Membuat peristiwa status di Google Apps Script

Google Apps Script adalah bahasa skrip cloud berbasis JavaScript yang memungkinkan Anda membuat aplikasi bisnis yang terintegrasi dengan Google Workspace. Skrip dikembangkan di editor kode berbasis browser, dan disimpan serta dijalankan di server Google. Lihat juga panduan memulai Google Apps Script untuk mulai menggunakan Apps Script untuk mengirim permintaan ke Google Calendar API.

Petunjuk berikut menjelaskan cara mengelola peristiwa status menggunakan Google Calendar API sebagai layanan lanjutan di Google Apps Script. Untuk mengetahui daftar lengkap referensi dan metode Google Calendar API, lihat dokumentasi referensi.

Membuat dan menyiapkan skrip

1. Buat skrip dengan membuka script.google.com/create.
2. Di panel kiri di samping Layanan, klik Tambahkan layanan .
3. Pilih Google Calendar API, lalu klik Tambahkan.
4. Setelah diaktifkan, API akan muncul di panel kiri. Metode dan class yang tersedia di API dapat dicantumkan menggunakan kata kunci Calendar di editor.

(Opsional) Update project Google Cloud

Setiap project Google Apps Script memiliki project Google Cloud yang terkait. Skrip Anda dapat menggunakan project default yang dibuat secara otomatis oleh Google Apps Script. Jika ingin menggunakan project Google Cloud kustom, lakukan langkah-langkah berikut untuk mengupdate project yang terkait dengan skrip Anda.

1. Di sisi kiri editor, klik Project Settings .
2. Pada Google Cloud Platform (GCP) Project, klik Change project.
3. Masukkan nomor project project Google Cloud yang ada dalam Program Pratinjau Developer, lalu klik Set project.
4. Di sebelah kiri, pilih Editor untuk kembali ke editor kode.

Menambahkan kode ke skrip

Contoh kode berikut menunjukkan cara membuat, membaca, dan mencantumkan peristiwa status di kalender utama Anda.

1. Tempelkan kode berikut ke dalam editor kode.

   primary adalah kata kunci untuk mengakses kalender utama pengguna yang login. Untuk mengambil acara di kalender lain, tetapkan parameter calendarId ke alamat email. Dengan begitu, Anda dapat membaca peristiwa status di kalender pengguna lain yang setidaknya memiliki akses bebas/sibuk. Kalender sekunder tidak dapat memiliki acara yang berstatus.

   /** Creates a focus time event. */
   function createFocusTime() {
     const event = {
       start: { dateTime: '2023-11-14T10:00:00+01:00' },
       end: { dateTime: '2023-11-14T12:00:00+01:00' },
       eventType: 'focusTime',
       focusTimeProperties: {
         chatStatus: 'doNotDisturb',
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am in focus time.',
       }
     }
     createEvent(event);
   }
   
   /** Creates an out of office event. */
   function createOutOfOffice() {
     const event = {
       start: { dateTime: '2023-11-15T10:00:00+01:00' },
       end: { dateTime: '2023-11-15T18:00:00+01:00' },
       eventType: 'outOfOffice',
       outOfOfficeProperties: {
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am on vacation.',
       }
     }
     createEvent(event);
   }
   
   /** Creates a working location event. */
   function createWorkingLocation() {
     const event = {
       start: { date: "2023-06-01" },
       end: { date: "2023-06-02" },
       eventType: "workingLocation",
       visibility: "public",
       transparency: "transparent",
       workingLocationProperties: {
         type: 'customLocation',
         customLocation: { label: "a custom location" },
       }
     }
     createEvent(event);
   }
   
   /**
     * Creates a Calendar event.
     * See https://developers.google.com/calendar/api/v3/reference/events/insert
     */
   function createEvent(event) {
     const calendarId = 'primary';
   
     try {
       var response = Calendar.Events.insert(event, calendarId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Reads the event with the given eventId.
     * See https://developers.google.com/calendar/api/v3/reference/events/get
     */
   function readEvent() {
     const calendarId = 'primary';
   
     // Replace with a valid eventId.
     const eventId = "sample-event-id";
   
     try {
       var response = Calendar.Events.get(calendarId, eventId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /** Lists focus time events. */
   function listFocusTimes() {
     listEvents('focusTime');
   }
   
   /** Lists out of office events. */
   function listOutOfOffices() {
     listEvents('outOfOffice');
   }
   
   /** Lists working location events. */
   function listWorkingLocations() {
     listEvents('workingLocation');
   }
   
   /**
     * Lists events with the given event type.
     * See https://developers.google.com/calendar/api/v3/reference/events/list
     */
   function listEvents(eventType = 'default') {
     const calendarId = 'primary'
   
     // Query parameters for the list request.
     const optionalArgs = {
       eventTypes: [eventType],
       showDeleted: false,
       singleEvents: true,
       timeMax: '2023-04-01T00:00:00+01:00',
       timeMin: '2023-03-27T00:00:00+01:00',
     }
     try {
       var response = Calendar.Events.list(calendarId, optionalArgs);
       response.items.forEach(event =>
         console.log(eventType === 'workingLocation' ? parseWorkingLocation(event) : event));
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Parses working location properties of an event into a string.
     * See https://developers.google.com/calendar/api/v3/reference/events#resource
     */
   function parseWorkingLocation(event) {
     if (event.eventType != "workingLocation") {
       throw new Error("'" + event.summary + "' is not a working location event.");
     }
   
     var location = 'No Location';
     const workingLocation = event.workingLocationProperties;
     if (workingLocation) {
       if (workingLocation.type === 'homeOffice') {
         location = 'Home';
       }
       if (workingLocation.type === 'officeLocation') {
         location = workingLocation.officeLocation.label;
       }
       if (workingLocation.type === 'customLocation') {
         location = workingLocation.customLocation.label;
       }
     }
     return `${event.start.date}: ${location}`;
   }
   

Menjalankan contoh kode

1. Di atas editor kode, pilih fungsi yang akan dijalankan dari menu drop-down, lalu klik Run.
2. Pada eksekusi pertama, Anda akan diminta untuk memberikan otorisasi akses. Tinjau dan izinkan Apps Script mengakses kalender Anda.
3. Anda dapat memeriksa hasil eksekusi skrip di Execution Log yang muncul di bagian bawah jendela.