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ọ có đ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 ở một vị trí nhất định hay không.

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à chỉ được cung cấp 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 trên Lịch

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

Để đọ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 Calendar API.

Sử dụng phương thức events.watch, chỉ định calendarId của Lịch cần đă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 phiên bản 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 có thời gian (có chỉ định thời gian bắt đầu và kết thúc).
Thời gian 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 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 một 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 thể là sự kiện 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 các trường start và end của sự kiện thành một trong hai giá trị sau:
- Sự kiện có thời gian (có chỉ định thời gian bắt đầu và kết thúc);
- Một sự kiện diễn ra 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 có thể.

Các trường sau đây là không bắt buộc nhưng bạn nên 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 một 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ư gợi ý về 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ã nhận dạng và nhãn của toà nhà bằng phương thức resources.buildings.list.

Không hỗ trợ việc tạo và cập nhật các sự kiện vị trí 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 này, hãy xem bài viết Đặ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 thị các sự kiện trùng lặp về đị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à các sự kiện này 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 thiết lập. Trong trường hợp chỉ có thể cho người dùng thấy một vị trí duy nhất, thì vị trí đó phải xuất hiện 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 cần hiển thị:

Sự kiện có thời gian cụ thể sẽ được ưu tiên hơn sự kiện diễn ra cả ngày.
Sự kiện một lần sẽ được ưu tiên hơn sự kiện định kỳ và ngoại lệ của sự kiện đó.
Những sự kiện bắt đầu muộn hơn sẽ được ưu tiên hơn những sự kiện bắt đầu sớm hơn.
Những sự kiện có thời lượng ngắn hơn sẽ được ưu tiên hơn những 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 những sự kiện được tạo trước đó.
Các sự kiện chồng chéo một phần sẽ xuất hiện dưới dạng hai sự kiện riêng biệt, mỗi sự kiện có vị trí 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 đám mây dựa trên JavaScript, cho phép bạn tạo các ứng dụng 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 chỉnh sửa 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 Hướng dẫn nhanh về Google Apps Script để bắt đầu sử dụng Apps Script nhằm gửi yêu cầu đến Google Calendar API.

Các 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 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.
Trong ngăn bên trái, bên cạnh 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 đượ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ó trong API bằng cách sử dụ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 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 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 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 mục 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 dùng thử 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 chỉnh sửa 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 chỉnh sửa 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 các 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ó ít nhất quyền truy cập xem tình trạng 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 chỉnh sửa mã, hãy chọn hàm cần chạy trong trình đơn thả xuống, rồi nhấp vào Chạy.
Trong lần thực thi đầu tiên, hệ thống sẽ nhắc bạn uỷ quyền 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ê các sự kiện trạng thái trên 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 trên Lịch

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

Tạo trạng thái 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 trùng lặp về địa điểm làm việc

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 Google Cloud

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