Trang này được dịch bởi Cloud Translation API.

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 vị trí 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, 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 để cho biết trạng thái và vị trí tuỳ chỉnh của họ. Các tính năng này chỉ có trên lịch chính và cho một số người dùng Lịch Google.

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

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

Bạn có thể đọc và liệt kê các 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ê các 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 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 tin về các thay đổi đối với sự kiện trạng thái

Bạn có thể đăng ký nhận các thay đổi về 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 trong trường eventTypes:

'focusTime'
'outOfOffice'
'workingLocation'

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

Để tạo một sự kiện trạng thái, bạn sẽ tạo một bản sao của tài nguyên Events 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 phương thức events.update, 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 các trường start và end của sự kiện thành một sự kiện đã tính giờ (trong đó thời gian bắt đầu và kết thúc được chỉ định).
Thời gian cần tập trung không được 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 bài viết Sử dụng thời gian cần tập trung trong Lịch Google

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 các trường start và end của sự kiện thành một sự kiện đã tính giờ (trong đó 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ị khi 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 các trường start và end của sự kiện thành:
- Sự kiện được tính giờ (với thời gian bắt đầu và thời gian kết thúc được chỉ định);
- Một sự kiện cả ngày (với ngày bắt đầu và ngày kết thúc được chỉ định) kéo dài đúng 1 ngày.
Các 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 các sự kiện được tính giờ thì có thể.

Sau đây là các trường không bắt buộc nhưng bạn nên sử dụng để có trải nghiệm người dùng tốt nhất khi chèn officeLocation:

workingLocationProperties.officeLocation.buildingId: Giá trị 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ừ mọi tính năng của Lịch, ví dụ: tính năng đề xuất phòng.
workingLocationProperties.officeLocation.label: Đây là nhãn hiển thị trên ứng dụng Lịch dành cho web và thiết bị 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.

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

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

Cách hiện các sự kiện chồng chéo địa điểm làm việc

Người dùng có thể có nhiều sự kiện địa điểm làm việc trên lịch cùng một lúc và bị trùng lặp, 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. Trong các trường hợp khi chỉ một vị trí có thể hiển thị cho người dùng, họ phải hiển thị vị trí đó một cách 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 sẽ hiển thị:

Sự kiện được định thời gian được ưu tiên so với các sự kiện cả ngày.
Sự kiện đơn đượ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 đó.
Những sự kiện bắt đầu sau đó sẽ được ưu tiên hơn những sự kiện bắt đầu sớm hơn.
Các sự kiện có thời lượng ngắn hơn sẽ được ưu tiên hơn các sự kiện có thời lượng dài hơn.
Những sự kiện được tạo gần đây sẽ được ưu tiên hơn so với những sự kiện được tạo trước đó.
Các sự kiện trùng lặp một phần nên được hiển thị dưới dạng hai sự kiện khác nhau, mỗi sự kiện có đị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ữ viết tập lệnh trên đám mây dựa trên JavaScript, cho phép bạn tạo các ứng dụng dành cho doanh nghiệp tích hợp với Google Workspace. Tập lệnh được phát triển trong trình soạn thảo mã dựa trên trình duyệt và được lưu trữ cũng như chạy trên các máy chủ của Google. Ngoài ra, hãy xem phần Bắt đầu nhanh Google Apps Script để bắt đầu sử dụng Apps Script nhằm gửi yêu cầu đến API Lịch Google.

Hướng dẫn sau đây mô tả cách quản lý các sự kiện trạng thái bằng API Lịch Google làm dịch vụ nâng cao trong Google Apps Script. Để biết 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 tập lệnh bằng cách truy cập vào script.google.com/create.
Trong ngăn bên trái bên cạnh phần Services (Dịch vụ), hãy nhấp vào biểu tượng Add a service (Thêm dịch vụ) .
Chọn API Lịch Google rồi nhấp vào Thêm.
Sau khi được bật, API sẽ xuất hiệ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 cách sử dụng từ khoá Lịch trong trình chỉnh sửa.

(Không bắt buộc) Cập nhật dự án trên Google Cloud

Mỗi dự án Google Apps Script đều có một dự án Google Cloud liên kết. 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 Google Cloud tuỳ chỉnh, hãy làm theo các bước sau để cập nhật dự án liên kết với tập lệnh của bạn.

Ở 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 Dự án Google Cloud Platform (GCP), hãy nhấp vào Thay đổi dự án.
Nhập số dự án của dự án trên Google Cloud trong Chương trình Bản dùng thử cho nhà phát triển rồi nhấp vào Set project (Đặt dự án).
Ở phía bên trái, hãy chọn Trình chỉnh sửa để 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 biết cách tạo, đọc và liệt kê các sự kiện trạng thái trên lịch chính của bạn.

Dán nội dung sau đây vào trình soạn thảo mã.

primary là từ khóa để 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 cá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 rảnh/bận ở mức tối thiểu. 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/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}`;
}

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, ứng dụng sẽ nhắc bạn cấp quyền truy cập. Xem lại 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 Nhật ký thực thi xuất hiện ở cuối cửa sổ.