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 lokasi pengguna atau apa yang mereka lakukan, termasuk apakah mereka sedang dalam 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 acara status Kalender di resource Events dari Calendar API.

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

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

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

Kemudian, di 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 memantau perubahan pada peristiwa status di resource Events dari Calendar API.

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

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

Membuat dan memperbarui acara status Kalender

Untuk membuat peristiwa status, Anda membuat instance resource Events menggunakan metode events.insert, dengan menetapkan kolom yang diperlukan untuk jenis peristiwa.

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

Membuat waktu fokus

Untuk membuat acara waktu fokus:

• Tetapkan eventType ke 'focusTime'.
• Sertakan kolom focusTimeProperties.
• Tetapkan kolom transparency ke 'opaque'.
• Tetapkan kolom start dan end acara menjadi acara 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 pesan saat tidak di kantor

Untuk membuat acara tidak di kantor:

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

Untuk mengetahui detail fitur, buka Menampilkan jadwal saat Anda tidak di kantor

Membuat lokasi kerja

Untuk membuat acara 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 salah satu dari:

  • 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 mencakup beberapa hari, tetapi acara terjadwal dapat mencakup beberapa hari.

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

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

Pembuatan dan pembaruan acara 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 peristiwa lokasi kerja di kalendernya secara bersamaan yang tumpang-tindih, yang berarti bahwa setiap waktu tertentu dapat memiliki beberapa lokasi kerja yang ditetapkan untuknya. Dalam situasi ketika hanya satu lokasi yang dapat ditampilkan kepada pengguna, lokasi tersebut harus ditampilkan 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.
• Acara tunggal lebih diprioritaskan daripada acara berulang dan pengecualiannya.
• Acara yang dimulai lebih lambat akan diutamakan daripada acara yang dimulai lebih awal.
• Acara dengan durasi yang lebih singkat lebih diutamakan daripada acara dengan durasi yang lebih panjang.
• Peristiwa yang dibuat baru-baru ini lebih diutamakan daripada peristiwa yang dibuat sebelumnya.
• Acara yang tumpang-tindih sebagian harus ditampilkan sebagai dua acara berbeda dengan lokasi kerja masing-masing.

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 mulai cepat Google Apps Script untuk mulai menggunakan Apps Script guna 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 resource 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) Perbarui 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 Anda ingin menggunakan project Google Cloud kustom, lakukan langkah-langkah berikut untuk memperbarui project yang terkait dengan skrip Anda.

1. Di sisi kiri editor, klik Setelan Project .
2. Pada Google Cloud Platform (GCP) Project, klik Change project.
3. Masukkan nomor project Google Cloud yang tergabung dalam Program Pratinjau Developer, lalu klik Set project.
4. Di sisi 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 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 acara status di kalender pengguna lain yang setidaknya memiliki akses gratis/sibuk. Kalender sekunder tidak dapat memiliki acara status.

   /** 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/workspace/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/workspace/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/workspace/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/workspace/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}`;
   }
   

Jalankan 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 mengotorisasi 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.