Quản lý thời gian cần tập trung, sự kiện không có mặt tại văn phòng và sự kiện tại địa điểm làm việc

Trang này giải thích cách sử dụng API Lịch Google để tạo sự kiện cho biết trạng thái của người dùng Lịch Google. Sự kiện trạng thái mô tả vị trí của người dùng hoặc việc họ đang làm, bao gồm cả việc họ đang trong thời gian cần tập trung, không có mặt tại văn phòng hay đang làm việc tại một địa điểm nhất định.

Trong Lịch Google, người dùng có thể tạo sự kiện thời gian cần tập trung, không có mặt tại văn phòng và địa điểm làm việc để cho biết trạng thái và địa điểm tuỳ chỉnh của họ. Các tính năng này chỉ có trên lịch chính và dành cho một số người dùng Lịch Google.

Để biết thêm thông tin chi tiết, hãy chuyển đến phần Sử dụng thời gian cần tập trung trong Lịch Google và Bật hoặc tắt địa điểm làm việc cho người dùng.

Đọc và liệt kê sự kiện trạng thái lịch

Bạn có thể đọc và liệt kê sự kiện trạng thái lịch trong tài nguyên Events của API Lịch.

Để đọc một sự kiện trạng thái, hãy sử dụng phương thức events.get, chỉ định eventId của sự kiện.

Để liệt kê sự kiện trạng thái, hãy sử dụng phương thức events.list, chỉ định một hoặc nhiều giá trị sau đây trong trường eventTypes:

'focusTime'
'outOfOffice'
'workingLocation'

Sau đó, trong các đối tượng Event được trả về, hãy kiểm tra để đảm bảo trường eventType có giá trị được yêu cầu và tham khảo trường tương ứng để biết thông tin chi tiết về trạng thái do người dùng tạo trong Lịch Google:

Đăng ký nhận thông báo về các thay đổi đối với sự kiện trạng thái

Bạn có thể đăng ký nhận thông báo về các thay đổi đối với sự kiện trạng thái trong tài nguyên Events của API Lịch.

Sử dụng phương thức events.watch, chỉ định calendarId của Lịch để đăng ký và một hoặc nhiều giá trị sau đây trong trường eventTypes:

'focusTime'
'outOfOffice'
'workingLocation'

Tạo và cập nhật sự kiện trạng thái lịch

Để tạo một sự kiện trạng thái, bạn hãy tạo một thực thể của Events tài nguyên bằng phương thức events.insert, đặt các trường bắt buộc cho loại sự kiện.

Nếu bạn cập nhật sự kiện trạng thái bằng events.update phương thức, thì sự kiện đó phải duy trì các trường bắt buộc.

Tạo thời gian cần tập trung

Cách tạo sự kiện thời gian cần tập trung:

Đặt eventType thành 'focusTime'.
Thêm trường focusTimeProperties.
Đặt trường transparency thành 'opaque'.
Đặt trường start và end của sự kiện thành một sự kiện có thời gian (có thời gian bắt đầu và kết thúc được chỉ định).
Thời gian cần tập trung không thể là sự kiện cả ngày.

Để biết thông tin chi tiết về tính năng, hãy chuyển đến phần Sử dụng thời gian cần tập trung trong Google Lịch

Tạo sự kiện không có mặt tại văn phòng

Cách tạo sự kiện không có mặt tại văn phòng:

Đặt eventType thành 'outOfOffice'.
Thêm trường outOfOfficeProperties.
Đặt trường transparency thành 'opaque'.
Đặt trường start và end của sự kiện thành một sự kiện có thời gian (có thời gian bắt đầu và kết thúc được chỉ định).
Sự kiện không có mặt tại văn phòng không thể là sự kiện cả ngày.

Để biết thông tin chi tiết về tính năng, hãy chuyển đến phần Hiển thị thời điểm bạn không có mặt tại văn phòng

Tạo địa điểm làm việc

Cách tạo sự kiện địa điểm làm việc:

Đặt eventType thành 'workingLocation'.
Thêm trường workingLocationProperties.
Đặt trường visibility thành 'public'.
Đặt trường transparency thành 'transparent'.
Đặt trường start và end của sự kiện thành:
- Một sự kiện có thời gian (có thời gian bắt đầu và kết thúc được chỉ định);
- Một sự kiện cả ngày (có ngày bắt đầu và kết thúc được chỉ định) kéo dài đúng một ngày.
Sự kiện địa điểm làm việc cả ngày không thể kéo dài nhiều ngày, nhưng sự kiện có thời gian thì có thể.

Bạn có thể bỏ qua các trường sau đây nhưng nên sử dụng để mang lại trải nghiệm tốt nhất cho người dùng khi chèn officeLocation:

workingLocationProperties.officeLocation.buildingId: Trường này phải khớp với buildingId trong cơ sở dữ liệu tài nguyên của tổ chức. Điều này giúp người dùng hưởng lợi từ tất cả các tính năng của Lịch, chẳng hạn như đề xuất phòng.
workingLocationProperties.officeLocation.label: Đây là nhãn xuất hiện trên Lịch trên web và ứng dụng di động. Bạn có thể tìm nạp mã toà nhà và nhãn toà nhà bằng phương thức resources.buildings.list.

Chúng tôi không hỗ trợ việc tạo và cập nhật sự kiện địa điểm làm việc thông qua các điểm cuối hàng loạt.

Để biết thông tin chi tiết về tính năng, hãy chuyển đến phần Đặt địa điểm làm việc và giờ làm việc và Bật hoặc tắt địa điểm làm việc cho người dùng

Cách hiển thị các sự kiện địa điểm làm việc trùng lặp

Một người dùng có thể có nhiều sự kiện địa điểm làm việc trên lịch của họ cùng một lúc và trùng lặp. Điều này có nghĩa là bất kỳ thời điểm nào cũng có thể có nhiều địa điểm làm việc được đặt cho thời điểm đó. Trong trường hợp chỉ có thể hiển thị một địa điểm cho người dùng, thì địa điểm đó phải được hiển thị nhất quán trên nhiều ứng dụng. Khi thực hiện việc này, hãy sử dụng các nguyên tắc sau để chọn sự kiện cần hiển thị:

Sự kiện có thời gian sẽ được ưu tiên hơn sự kiện cả ngày.
Sự kiện đơn lẻ sẽ được ưu tiên hơn sự kiện định kỳ và các trường hợp ngoại lệ của sự kiện đó .
Sự kiện bắt đầu muộn hơn sẽ được ưu tiên hơn sự kiện bắt đầu sớm hơn.
Sự kiện có thời lượng ngắn hơn sẽ được ưu tiên hơn sự kiện có thời lượng dài hơn.
Sự kiện được tạo gần đây hơn sẽ được ưu tiên hơn sự kiện được tạo trước đó.
Sự kiện trùng lặp một phần sẽ được hiển thị dưới dạng hai sự kiện riêng biệt, mỗi sự kiện có một địa điểm làm việc riêng.

Tạo sự kiện trạng thái trong Google Apps Script

Google Apps Script là một ngôn ngữ kịch bản dựa trên JavaScript trên đám mây, cho phép bạn xây dựng các ứng dụng dành cho doanh nghiệp tích hợp với Google Workspace. Các tập lệnh được phát triển trong một trình soạn thảo mã dựa trên trình duyệt, đồng thời được lưu trữ và chạy trên máy chủ của Google. Bạn cũng có thể xem bài viết Bắt đầu nhanh với Google Apps Script để bắt đầu sử dụng Apps Script gửi yêu cầu đến API Lịch Google.

Các hướng dẫn sau đây mô tả cách quản lý sự kiện trạng thái bằng API Lịch Google dưới dạng một dịch vụ nâng cao trong Google Apps Script. Để xem danh sách đầy đủ các tài nguyên và phương thức của API Lịch Google, hãy xem tài liệu tham khảo.

Tạo và thiết lập tập lệnh

Tạo một tập lệnh bằng cách truy cập vào script.google.com/create.
Trên ngăn bên trái bên cạnh Services (Dịch vụ), hãy nhấp vào biểu tượng Thêm dịch vụ .
Chọn Google Calendar API (API Lịch Google) rồi nhấp vào Add (Thêm).
Sau khi được bật, API sẽ xuất hiện trên ngăn bên trái. Bạn có thể liệt kê các phương thức và lớp có sẵn trong API bằng từ khoá Calendar trong trình chỉnh sửa.

(Không bắt buộc) Cập nhật dự án trên đám mây

Mỗi dự án Google Apps Script đều có một dự án liên kết trên Google Cloud. Tập lệnh của bạn có thể sử dụng dự án mặc định mà Google Apps Script tự động tạo. Nếu bạn muốn sử dụng một dự án trên đám mây tuỳ chỉnh trên Google Cloud, hãy thực hiện các bước sau để cập nhật dự án được liên kết với tập lệnh.

Ở bên trái trình chỉnh sửa, hãy nhấp vào biểu tượng Cài đặt dự án .
Trong mục Google Cloud Platform (GCP) Project (Dự án trên Google Cloud Platform (GCP)), hãy nhấp vào Change project (Thay đổi dự án).
Nhập số dự án của dự án trên Google Cloud thuộc Chương trình dùng trước dành cho nhà phát triển rồi nhấp vào Set project (Đặt dự án).
Ở bên trái, hãy chọn Trình soạn thảo mã để quay lại trình soạn thảo mã.

Thêm mã vào tập lệnh

Mã mẫu sau đây cho thấy cách tạo, đọc và liệt kê sự kiện trạng thái trên lịch chính.

Dán mã sau vào trình soạn thảo mã.

primary là một từ khoá để truy cập vào lịch chính của người dùng đã đăng nhập. Để truy xuất sự kiện trên một lịch khác, hãy đặt tham số calendarId thành một địa chỉ email. Điều này cho phép bạn đọc sự kiện trạng thái trên lịch của những người dùng khác mà bạn có quyền truy cập tối thiểu là rảnh/bận. Lịch phụ không thể có sự kiện trạng thái.

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

Chạy mã mẫu

Phía trên trình soạn thảo mã, hãy chọn hàm cần chạy trong trình đơn thả xuống rồi nhấp vào Run (Chạy).
Trong lần thực thi đầu tiên, hệ thống sẽ nhắc bạn cho phép truy cập. Xem xét và cho phép Apps Script truy cập vào lịch của bạn.
Bạn có thể kiểm tra kết quả thực thi tập lệnh trong Execution Log (Nhật ký thực thi) xuất hiện ở cuối cửa sổ.

Quản lý thời gian cần tập trung, sự kiện không có mặt tại văn phòng và sự kiện tại địa điểm làm việc Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Đọc và liệt kê sự kiện trạng thái lịch

Đăng ký nhận thông báo về các thay đổi đối với sự kiện trạng thái

Tạo và cập nhật sự kiện trạng thái lịch

Tạo thời gian cần tập trung

Tạo sự kiện không có mặt tại văn phòng

Tạo địa điểm làm việc

Cách hiển thị các sự kiện địa điểm làm việc trùng lặp

Tạo sự kiện trạng thái trong Google Apps Script

Tạo và thiết lập tập lệnh

(Không bắt buộc) Cập nhật dự án trên đám mây

Thêm mã vào tập lệnh

Chạy mã mẫu

Quản lý thời gian cần tập trung, sự kiện không có mặt tại văn phòng và sự kiện tại địa điểm làm việc