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 các 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 ở trạng thái tập trung, vắng mặt hay làm việc ở 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, 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à 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à 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 xem 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 vị trí làm việc cho người dùng.

Đọc và liệt kê các sự kiện 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 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 trong trường eventTypes:

'focusTime'
'outOfOffice'
'workingLocation'

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

Để tạo một sự kiện trạng thái, bạn tạo một thực thể của tài nguyên Events bằng phương thức events.insert, thiết lập 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 sự kiện có thời gian (có chỉ định thời gian bắt đầu và kết thúc).
Thời gian cần tập trung không được là sự kiện diễn ra cả ngày.

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

Tạo trạng thái 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 sự kiện có thời gian (có chỉ định thời gian bắt đầu và kết thúc).
Sự kiện không có mặt tại văn phòng không được là sự kiện diễn ra cả ngày.

Để biết thông tin chi tiết về tính năng này, hãy xem bài viết 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:
- 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 kéo dài cả ngày (có ngày bắt đầu và ngày kết thúc được chỉ định) kéo dài đúng một ngày.
Sự kiện tại đị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 bắt đầu và kết thúc thì có thể.

Các trường sau đây là không bắt buộc nhưng bạn 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: 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ừ tất 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 ứng dụng 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.

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

Để biết thông tin chi tiết về tính năng này, hãy xem bài viết Đặt giờ làm việc và địa điểm 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 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 với nhau, tức 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 sự kiện đó. Trong trường hợp chỉ có thể hiển thị một vị trí cho người dùng, họ phải thấy 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 làm theo các nguyên tắc sau để chọn sự kiện sẽ hiển thị:

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

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

Google Apps Script là một ngôn ngữ tập lệnh đám mây dựa trên JavaScript, cho phép bạn xây dựng các ứng dụng kinh doanh 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, đồng thời được lưu trữ và chạy trên máy chủ của Google. Xem thêm phần Bắt đầu nhanh với 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 cách sử dụng API Lịch Google làm 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 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 mục Dịch vụ, hãy nhấp vào biểu tượng Thêm dịch vụ .
Chọn Google Calendar API rồi nhấp vào Thêm.
Sau khi 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 cách sử dụng từ khoá Calendar (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 được 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 được liên kết với tập lệnh của bạn.

Ở bên trái của trình chỉnh sửa, hãy nhấp vào biểu tượng Cài đặt dự án .
Trong phần Dự án trên Google Cloud Platform (GCP), hãy nhấp vào Thay đổi dự án.
Nhập số dự án của dự án Google Cloud có trong Chương trình xem trước dành cho nhà phát triển rồi nhấp vào Đặt dự án.
Ở bên trái, hãy chọn biểu tượng 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 vào trình soạn thảo mã.

chính là 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 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 ở mức 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/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 để 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 uỷ 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 Execution Log (Nhật ký thực thi) xuất hiện ở cuối cửa sổ.