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 hiển thị 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 họ đang làm gì, bao gồm cả việc họ đang tập trung, không có mặt tại văn phòng hay 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 thời gian cần tập trung, không có mặt tại văn phòng và làm việc sự kiện vị trí để cho biết trạng thái và vị trí tuỳ chỉnh của chúng. Những tính năng này chỉ có trên lịch chính và đối với 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 Google Lịch và Bật hoặc tắt địa điểm làm việc cho người dùng.

Đọc và liệt kê các sự kiện liên quan đế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 phần API Lịch.

Để đọc một sự kiện trạng thái, hãy sử dụng events.get, chỉ định phương thức 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 phương thức hoặc nhiều giá trị sau trong phần Trường eventTypes:

'focusTime'
'outOfOffice'
'workingLocation'

Sau đó, trong các đối tượng Event được trả về, hãy kiểm tra xem 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 các thay đổi về các 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 phần API Lịch.

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

'focusTime'
'outOfOffice'
'workingLocation'

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

Để tạo sự kiện trạng thái, bạn hãy tạo một phiên bản của Tài nguyên Events bằng cách sử dụng events.insert, đặt giá trị 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 cách sử dụng events.update, 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'.
Bao gồm focusTimeProperties .
Đặt transparency sang 'opaque'.
Đặt start của sự kiện và end trường là sự kiện được tính giờ (đã xác định thời gian bắt đầu và thời gian kết thúc).
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 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'.
Bao gồm outOfOfficeProperties .
Đặt transparency sang 'opaque'.
Đặt start của sự kiện và end trường là sự kiện được tính giờ (đã xác định thời gian bắt đầu và thời gian 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 cả ngày.

Để xem thông tin chi tiết về tính năng, hãy chuyển đến phần Hiển thị khi bạn rời khỏi văn phòng

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

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

Đặt eventType thành 'workingLocation'.
Bao gồm workingLocationProperties .
Đặt trường visibility đến 'public'.
Đặt transparency sang 'transparent'.
Đặt start của sự kiện và end sẽ là các trường:
- Sự kiện được tính giờ (trong đó thời gian bắt đầu và thời gian kết thúc được chỉ định);
- Sự kiện cả ngày (đã chỉ định ngày bắt đầu và ngày kết thúc) kéo dài đúng một ngày.
Sự kiện diễn ra cả ngày tại địa điểm làm việc không thể kéo dài nhiều ngày, mà là các sự kiện được lên lịch có thể.

Sau đây là các trường 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 một officeLocation:

workingLocationProperties.officeLocation.buildingId: Số này phải khớp với một buildingId trong thuộc tính của tổ chức tài nguyên cơ sở dữ liệu. Đ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 Google, chẳng hạn như đề xuất phòng.
workingLocationProperties.officeLocation.label: Đây là nhãn được hiển thị trên các ứng dụng khách của Lịch trên web và thiết bị di động. Bạn có thể tìm nạp mã nhận dạng toà nhà và nhãn toà nhà bằng cách sử dụng resources.buildings.list .

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

Để 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à vị trí và Bật hoặc tắt địa điểm làm việc cho người dùng

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

Người dùng có thể có nhiều sự kiện tại địa điểm làm việc trên lịch cùng một lúc trùng lặp, nghĩa là bất kỳ thời điểm nào cũng có thể có nhiều thời gian vị trí được thiết lập cho quảng cáo. Trong những trường hợp chỉ có thể hiển thị một vị trí 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 . 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 để hiển thị:

Sự kiện được tính giờ mất ưu tiên hơn các sự kiện cả ngày.
Các sự kiện đơn lẻ được ưu tiên hơn các sự kiện định kỳ và ngoại lệ.
Những sự kiện bắt đầu sau đó sẽ được ưu tiên so với 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 so với các sự kiện có thời lượng dài hơn thời lượng.
Sự kiện được tạo gần đây sẽ được ưu tiên hơn so với sự kiện được tạo trước đó.
Các sự kiện trùng lặp một phần sẽ được thể hiện dưới dạng 2 sự kiện khác nhau có địa điểm làm việc riêng.

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

Google Apps Script là một đám mây dựa trên JavaScript ngôn ngữ tập lệnh cho phép bạn xây dựng các ứng dụng kinh doanh tích hợp với Google Workspace. Các 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à chúng sẽ được lưu trữ và chạy trên các máy chủ của Google. Xem thêm Google Apps Script bắt đầu nhanh để 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ý các sự kiện trạng thái sử dụng API Lịch Google là 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 tập lệnh bằng cách chuyển đến script.google.com/create.
Trên ngăn bên trái, bên cạnh Dịch vụ, hãy nhấp vào Thêm dịch vụ .
Chọn API Lịch Google rồi nhấp vào Thêm.
Sau khi bật, API này sẽ xuất hiện trên ngăn bên trái. Các phương thức có thể sử dụng và các lớp trong API có thể được liệt kê 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 có một dự án liên kết với Google Cloud. Thông tin tập lệnh có thể tự động sử dụng dự án mặc định mà Google Apps Script tạo. Nếu bạn muốn sử dụng một dự án tuỳ chỉnh trên Google Cloud, 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 của trình chỉnh sửa, nhấp vào 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 thẻ dành cho Nhà phát triển Chương trình dùng thử, 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 để hãy 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 mình.

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

primary là một từ khoá để truy cập vào lịch của người dùng đã đăng nhập. Cách truy xuất các sự kiện trên một lịch khác: đặt tham số calendarId thành một địa chỉ email. Điều này cho phép bạn đọc ít nhất các sự kiện trạng thái trên lịch của người dùng khác mà bạn có rảnh/bận vào. Lịch phụ không thể có cá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 từ 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 cấp 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 Nhật ký thực thi xuất hiện ở cuối cửa sổ.