Halaman ini diterjemahkan oleh Cloud Translation API.

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 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 melihat daftar peristiwa status Kalender di resource Events pada Calendar API.

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

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

'focusTime'
'outOfOffice'
'workingLocation'

Kemudian, pada 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:

Berlangganan info perubahan peristiwa status

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

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

'focusTime'
'outOfOffice'
'workingLocation'

Membuat dan memperbarui acara status Kalender

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

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

Buat waktu fokus

Untuk membuat acara waktu fokus:

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

Untuk detail fitur, buka Menggunakan waktu fokus di Google Kalender

Buat acara 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 peristiwa sebagai peristiwa berjangka waktu (dengan waktu mulai dan berakhir yang ditentukan).
Acara tidak di kantor tidak boleh berupa acara sepanjang hari.

Untuk mengetahui detail fitur, buka Menampilkan 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 ke:
- Peristiwa berjangka waktu (dengan waktu mulai dan berakhir telah ditentukan);
- Acara sepanjang hari (dengan tanggal mulai dan akhir yang ditentukan) yang berlangsung tepat satu hari.
Acara lokasi kerja sepanjang hari tidak dapat menjangkau beberapa hari, tetapi acara berjangka waktu dapat melakukannya.

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

workingLocationProperties.officeLocation.buildingId: Nilai ini harus cocok dengan buildingId di 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 klien seluler dan Web Kalender. Anda dapat mengambil ID gedung 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 acara lokasi kerja yang tumpang-tindih

Pengguna dapat memiliki beberapa acara lokasi kerja di kalender mereka secara bersamaan yang tumpang-tindih, yang berarti bahwa pada waktu tertentu, beberapa lokasi kerja dapat ditetapkan untuk acara tersebut. 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 peristiwa yang akan ditampilkan:

Peristiwa berbatas waktu lebih diutamakan daripada peristiwa sepanjang hari.
Peristiwa tunggal lebih diutamakan daripada peristiwa berulang dan pengecualiannya.
Peristiwa yang dimulai kemudian akan lebih diutamakan daripada peristiwa yang dimulai lebih awal.
Peristiwa dengan durasi yang lebih singkat akan diprioritaskan daripada peristiwa dengan durasi yang lebih lama.
Peristiwa yang baru dibuat lebih diutamakan daripada peristiwa yang dibuat sebelumnya.
Peristiwa yang tumpang-tindih sebagian harus ditampilkan sebagai dua peristiwa berbeda yang masing-masing dengan lokasi kerjanya sendiri.

Membuat peristiwa status di Google Apps Script

Google Apps Script adalah bahasa pembuatan skrip cloud berbasis JavaScript yang memungkinkan Anda membangun 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 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 daftar lengkap resource dan metode Google Calendar API, lihat dokumentasi referensi.

Membuat dan menyiapkan skrip

Buat skrip dengan membuka script.google.com/create.
Pada panel kiri di samping Services, klik Add a service .
Pilih Google Calendar API, lalu klik Add.
Setelah diaktifkan, API akan muncul di panel kiri. Metode dan class yang tersedia di API dapat dicantumkan menggunakan kata kunci Kalender 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 otomatis oleh Google Apps Script. Jika ingin menggunakan project Google Cloud kustom, lakukan langkah-langkah berikut untuk mengupdate project yang terkait dengan skrip Anda.

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

Menambahkan kode ke skrip

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

Tempel 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 minimum senggang/sibuk Anda. Kalender sekunder tidak boleh 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/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

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