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. Acara status menjelaskan lokasi pengguna atau aktivitas 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 acara status Kalender

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

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

Untuk mencantumkan acara 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 acara status

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

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

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

Membuat dan memperbarui acara status Kalender

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

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

Membuat waktu fokus

Untuk membuat acara waktu fokus:

• Tetapkan eventType ke 'focusTime'.
• Sertakan kolom focusTimeProperties.
• Tetapkan transparency kolom ke 'opaque'.
• Tetapkan kolom start dan end acara sebagai acara berwaktu (dengan waktu mulai dan berakhir yang ditentukan).
  Waktu fokus tidak dapat 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 outOfOfficeProperties kolom.
• Tetapkan transparency kolom ke 'opaque'.
• Tetapkan kolom start dan end acara sebagai 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 status tidak di kantor

Membuat lokasi kerja

Untuk membuat acara lokasi kerja:

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

• Tetapkan kolom start dan end acara sebagai:

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

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

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

• workingLocationProperties.officeLocation.buildingId:Kolom ini harus cocok dengan buildingId dalam 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 resources.buildings.list metode.

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 acara lokasi kerja yang tumpang-tindih

Pengguna dapat memiliki beberapa acara lokasi kerja di kalender mereka pada saat yang sama yang tumpang-tindih, yang berarti bahwa setiap waktu tertentu dapat memiliki beberapa lokasi kerja yang ditetapkan. Jika hanya satu lokasi yang dapat ditampilkan kepada pengguna, lokasi tersebut harus ditampilkan secara konsisten di beberapa aplikasi. Saat melakukannya, gunakan panduan berikut untuk memilih acara yang akan ditampilkan:

• Acara berwaktu lebih diutamakan daripada acara sepanjang hari.
• Acara tunggal lebih diutamakan daripada acara berulang dan pengecualiannya .
• Acara yang dimulai nanti lebih diutamakan daripada acara yang dimulai lebih awal.
• Acara dengan durasi yang lebih singkat lebih diutamakan daripada acara dengan durasi yang lebih lama.
• Acara yang dibuat baru-baru ini lebih diutamakan daripada acara yang dibuat sebelumnya.
• Acara yang tumpang-tindih sebagian harus ditampilkan sebagai dua acara berbeda, masing-masing dengan lokasi kerjanya sendiri.

Membuat acara 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 Google Apps Script quickstart untuk mulai menggunakan Apps Script guna mengirim permintaan ke Google Calendar API.

Petunjuk berikut menjelaskan cara mengelola acara 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) Memperbarui project Google Cloud

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

1. Di sisi kiri editor, klik Setelan project .
2. Di bagian Project Google Cloud Platform (GCP), klik Ubah project.
3. Masukkan nomor project Google Cloud yang ada di Program Pratinjau Developer, lalu klik Tetapkan 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 acara 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. Hal ini memungkinkan Anda membaca acara status di kalender pengguna lain yang memiliki akses minimal 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}`;
   }
   

Menjalankan contoh kode

1. Di atas editor kode, pilih fungsi yang akan dijalankan dari menu drop-down, lalu klik Jalankan.
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 Log Eksekusi yang muncul di bagian bawah jendela.