Events: update

Cập nhật một sự kiện. Phương thức này không hỗ trợ ngữ nghĩa bản vá và luôn cập nhật toàn bộ tài nguyên sự kiện. Để cập nhật một phần, hãy thực hiện get, sau đó là update bằng cách sử dụng các thẻ điện tử để đảm bảo tính tỉ mỉ. Thử ngay hoặc xem ví dụ.

Yêu cầu

Yêu cầu HTTP

PUT https://www.googleapis.com/calendar/v3/calendars/calendarId/events/eventId

Thông số

Tên thông số Giá trị Mô tả
Tham số đường dẫn
calendarId string Giá trị nhận dạng lịch. Để truy xuất mã lịch, hãy gọi phương thức calendarList.list. Nếu bạn muốn truy cập lịch chính của người dùng hiện đang đăng nhập, hãy sử dụng "primary" từ khoá.
eventId string Giá trị nhận dạng sự kiện.
Tham số truy vấn không bắt buộc
alwaysIncludeEmail boolean Không được dùng nữa và bị bỏ qua. Đối với người tổ chức, người sáng tạo và người tham dự, giá trị sẽ luôn được trả về trong trường email, ngay cả khi không có địa chỉ email thực (tức là một giá trị được tạo ra, không hoạt động).
conferenceDataVersion integer Số phiên bản của dữ liệu hội nghị truyền hình được ứng dụng API hỗ trợ. Phiên bản 0 giả định không hỗ trợ dữ liệu hội nghị và bỏ qua dữ liệu hội nghị trong phần nội dung của sự kiện. Phiên bản 1 cho phép hỗ trợ sao chép Hội nghị dữ liệu cũng như tạo hội nghị mới sử dụng trường createRequest của meetingData. Giá trị mặc định là 0. Giá trị có thể chấp nhận là từ 0 đến 1.
maxAttendees integer Số người tham dự tối đa được đưa vào câu trả lời. Nếu số người tham dự vượt quá số người tham dự đã chỉ định thì chỉ có người tham gia đó mới được trả về. Không bắt buộc.
sendNotifications boolean Không dùng nữa. Thay vào đó, vui lòng sử dụng sendUpdates.

Liệu có gửi thông báo về thông tin cập nhật của sự kiện hay không (ví dụ: thay đổi nội dung mô tả, v.v.). Xin lưu ý rằng một số email vẫn có thể được gửi ngay cả khi bạn đặt giá trị thành false. Giá trị mặc định là false.
sendUpdates string Những khách cần nhận được thông báo về nội dung cập nhật của sự kiện (ví dụ: thay đổi tiêu đề, v.v.).

Các giá trị được chấp nhận là:
  • "all": Thông báo được gửi cho tất cả khách.
  • "externalOnly": Thông báo chỉ được gửi cho những khách không phải là khách là người dùng Lịch Google.
  • "none": Không có thông báo nào được gửi. Đối với các tác vụ di chuyển lịch, hãy cân nhắc sử dụng phương thức Events.import.
supportsAttachments boolean Liệu ứng dụng API có thực hiện thao tác có hỗ trợ tệp đính kèm sự kiện hay không. Không bắt buộc. Giá trị mặc định là False.

Ủy quyền

Yêu cầu này cần có sự uỷ quyền với ít nhất một trong các phạm vi sau:

Phạm vi
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events

Để biết thêm thông tin, hãy xem trang xác thực và uỷ quyền.

Nội dung yêu cầu

Trong nội dung yêu cầu, hãy cung cấp tài nguyên Sự kiện với các thuộc tính sau:

Tên tài sản Giá trị Mô tả Ghi chú
Thuộc tính bắt buộc
end nested object Thời gian kết thúc (loại trừ) của sự kiện. Đối với một sự kiện định kỳ, đây là thời gian kết thúc của lần diễn ra đầu tiên.
start nested object Thời gian bắt đầu (bao gồm) sự kiện. Đối với một sự kiện định kỳ, đây là thời gian bắt đầu sự kiện đầu tiên.
Thuộc tính không bắt buộc
anyoneCanAddSelf boolean Liệu bất kỳ ai cũng có thể tự mời mình tham gia sự kiện hay không (không dùng nữa). Không bắt buộc. Giá trị mặc định là False. có thể ghi
attachments[].fileUrl string Đường liên kết URL đến tệp đính kèm.

Để thêm tệp đính kèm trên Google Drive, hãy sử dụng định dạng tương tự như trong thuộc tính alternateLink của tài nguyên Files trong API Drive.

Bắt buộc khi thêm tệp đính kèm.

 có thể ghi
attendees[] list Những người tham dự sự kiện. Xem hướng dẫn Sự kiện với người tham dự để biết thêm thông tin về cách lên lịch sự kiện với những người dùng lịch khác. Các tài khoản dịch vụ cần sử dụng tính năng uỷ quyền trên toàn miền để điền danh sách người tham dự. có thể ghi
attendees[].additionalGuests integer Số lượng khách bổ sung. Không bắt buộc. Giá trị mặc định là 0. có thể ghi
attendees[].comment string Nhận xét của người tham dự về phản hồi của họ. Không bắt buộc. có thể ghi
attendees[].displayName string Tên của người tham dự, nếu có. Không bắt buộc. có thể ghi
attendees[].email string Địa chỉ email của người tham dự (nếu có). Trường này phải xuất hiện khi thêm người tham dự. Đó phải là một địa chỉ email hợp lệ theo RFC5322.

Bắt buộc khi thêm một người tham dự.

 có thể ghi
attendees[].optional boolean Đây có phải là người tham dự không bắt buộc hay không. Không bắt buộc. Giá trị mặc định là False. có thể ghi
attendees[].resource boolean Liệu người tham dự có phải là một tài nguyên hay không. Chỉ có thể đặt khi người tham dự được thêm vào sự kiện lần đầu tiên. Các nội dung sửa đổi tiếp theo sẽ bị bỏ qua. Không bắt buộc. Giá trị mặc định là False. có thể ghi
attendees[].responseStatus string Trạng thái phản hồi của người tham dự. Các giá trị có thể có là:
  • "needsAction" – Người tham dự chưa trả lời thư mời (được đề xuất cho các sự kiện mới).
  • "declined" – Người tham dự đã từ chối lời mời.
  • "tentative" – Người tham dự đã tạm thời chấp nhận lời mời.
  • "accepted" – Người tham dự đã chấp nhận lời mời.
 có thể ghi
attendeesOmitted boolean Liệu người tham dự có bị bỏ qua khỏi nội dung trình bày sự kiện hay không. Khi truy xuất một sự kiện, điều này có thể là do hạn chế được chỉ định bởi tham số truy vấn maxAttendee. Khi cập nhật một sự kiện, bạn chỉ có thể dùng tính năng này để cập nhật câu trả lời của người tham gia. Không bắt buộc. Giá trị mặc định là False. có thể ghi
colorId string Màu của sự kiện. Đây là mã nhận dạng tham chiếu đến một mục trong phần event của định nghĩa màu (xem điểm cuối màu). Không bắt buộc. có thể ghi
conferenceData nested object Thông tin liên quan đến hội nghị truyền hình, chẳng hạn như thông tin chi tiết về một hội nghị truyền hình trên Google Meet. Để tạo thông tin chi tiết mới về hội nghị truyền hình, hãy sử dụng trường createRequest. Để duy trì các thay đổi, hãy nhớ đặt tham số yêu cầu conferenceDataVersion thành 1 cho tất cả các yêu cầu sửa đổi sự kiện. có thể ghi
description string Mô tả về sự kiện. Có thể chứa HTML. Không bắt buộc. có thể ghi
end.date date Ngày, ở định dạng "yyyy-mm-dd", nếu đây là sự kiện cả ngày. có thể ghi
end.dateTime datetime Thời gian, dưới dạng một giá trị ngày-giờ kết hợp (được định dạng theo RFC3339). Bắt buộc phải có chênh lệch múi giờ trừ phi múi giờ được chỉ định rõ ràng trong timeZone. có thể ghi
end.timeZone string Múi giờ mà giờ được chỉ định. (Định dạng thành tên của Cơ sở dữ liệu múi giờ IANA, ví dụ: "Châu Âu/Zurich".) Đối với các sự kiện định kỳ, trường này là bắt buộc và chỉ định múi giờ mà sự kiện lặp lại được mở rộng. Đối với các sự kiện đơn lẻ, trường này là không bắt buộc và biểu thị múi giờ tùy chỉnh cho thời điểm bắt đầu/kết thúc sự kiện. có thể ghi
extendedProperties.private object Các thuộc tính riêng tư đối với bản sao của sự kiện xuất hiện trên lịch này. có thể ghi
extendedProperties.shared object Những thuộc tính được chia sẻ giữa các bản sao của sự kiện trên trang của những người tham dự khác lịch. có thể ghi
focusTimeProperties nested object Dữ liệu sự kiện trong Thời gian cần tập trung. Được dùng nếu eventType là focusTime. có thể ghi
gadget.display string Chế độ hiển thị của tiện ích. Không dùng nữa. Các giá trị có thể có là:
  • "icon" - Tiện ích này hiển thị bên cạnh tiêu đề sự kiện trong chế độ xem lịch.
  • "chip" - Tiện ích này hiển thị khi sự kiện được nhấp vào.
 có thể ghi
gadget.height integer Chiều cao của tiện ích tính bằng pixel. Chiều cao phải là số nguyên lớn hơn 0. Không bắt buộc. Không dùng nữa. có thể ghi
gadget.preferences object Tùy chọn. có thể ghi
gadget.title string Tiêu đề của tiện ích. Không dùng nữa. có thể ghi
gadget.type string Loại tiện ích. Không dùng nữa. có thể ghi
gadget.width integer Chiều rộng của tiện ích tính bằng pixel. Chiều rộng phải là một số nguyên lớn hơn 0. Không bắt buộc. Không dùng nữa. có thể ghi
guestsCanInviteOthers boolean Liệu người tham dự không phải người tổ chức có thể mời người khác tham gia sự kiện hay không. Không bắt buộc. Giá trị mặc định là "True". có thể ghi
guestsCanModify boolean Liệu người tham dự không phải người tổ chức có thể sửa đổi sự kiện hay không. Không bắt buộc. Giá trị mặc định là False. có thể ghi
guestsCanSeeOtherGuests boolean Liệu người tham dự không phải là người tổ chức có thể biết người tham dự sự kiện là ai không. Không bắt buộc. Giá trị mặc định là "True". có thể ghi
location string Vị trí địa lý của sự kiện dưới dạng văn bản tự do. Không bắt buộc. có thể ghi
originalStartTime.date date Ngày, ở định dạng "yyyy-mm-dd", nếu đây là sự kiện cả ngày. có thể ghi
originalStartTime.dateTime datetime Thời gian, dưới dạng một giá trị ngày-giờ kết hợp (được định dạng theo RFC3339). Bắt buộc phải có chênh lệch múi giờ trừ phi múi giờ được chỉ định rõ ràng trong timeZone. có thể ghi
originalStartTime.timeZone string Múi giờ mà giờ được chỉ định. (Định dạng thành tên của Cơ sở dữ liệu múi giờ IANA, ví dụ: "Châu Âu/Zurich".) Đối với các sự kiện định kỳ, trường này là bắt buộc và chỉ định múi giờ mà sự kiện lặp lại được mở rộng. Đối với các sự kiện đơn lẻ, trường này là không bắt buộc và biểu thị múi giờ tùy chỉnh cho thời điểm bắt đầu/kết thúc sự kiện. có thể ghi
outOfOfficeProperties nested object Dữ liệu sự kiện không có mặt tại văn phòng. Được dùng nếu eventType là outOfOffice. có thể ghi
recurrence[] list Danh sách các dòng RQU, EXRules, RDATE và EXDATE cho một sự kiện định kỳ, như được chỉ định trong RFC5545. Lưu ý rằng các đường DTSTART và DTEND không được phép trong trường này; thời gian bắt đầu và kết thúc của sự kiện được chỉ định trong trường start và end. Trường này bị bỏ qua đối với các sự kiện đơn lẻ hoặc lần diễn ra sự kiện định kỳ. có thể ghi
reminders.overrides[] list Nếu sự kiện không sử dụng lời nhắc mặc định, tuỳ chọn này sẽ liệt kê các lời nhắc dành riêng cho sự kiện hoặc nếu không được đặt, cho biết rằng chưa có lời nhắc nào được đặt cho sự kiện này. Số lượng lời nhắc ghi đè tối đa là 5. có thể ghi
reminders.overrides[].method string Phương thức mà lời nhắc này sử dụng. Các giá trị có thể có là:
  • "email" – Lời nhắc được gửi qua email.
  • "popup" – Lời nhắc được gửi qua cửa sổ bật lên trên giao diện người dùng.

Bắt buộc khi thêm lời nhắc.

 có thể ghi
reminders.overrides[].minutes integer Số phút trước khi bắt đầu sự kiện mà lời nhắc sẽ kích hoạt. Các giá trị hợp lệ nằm trong khoảng từ 0 đến 40320 (4 tuần tính bằng phút).

Bắt buộc khi thêm lời nhắc.

 có thể ghi
reminders.useDefault boolean Liệu lời nhắc mặc định của lịch có áp dụng cho sự kiện hay không. có thể ghi
sequence integer Số thứ tự theo iLịch. có thể ghi
source.title string Tiêu đề của nguồn tin; ví dụ như tiêu đề của một trang web hoặc chủ đề email. có thể ghi
source.url string URL của nguồn trỏ đến một tài nguyên. Lược đồ URL phải là HTTP hoặc HTTPS. có thể ghi
start.date date Ngày, ở định dạng "yyyy-mm-dd", nếu đây là sự kiện cả ngày. có thể ghi
start.dateTime datetime Thời gian, dưới dạng một giá trị ngày-giờ kết hợp (được định dạng theo RFC3339). Bắt buộc phải có chênh lệch múi giờ trừ phi múi giờ được chỉ định rõ ràng trong timeZone. có thể ghi
start.timeZone string Múi giờ mà giờ được chỉ định. (Định dạng thành tên của Cơ sở dữ liệu múi giờ IANA, ví dụ: "Châu Âu/Zurich".) Đối với các sự kiện định kỳ, trường này là bắt buộc và chỉ định múi giờ mà sự kiện lặp lại được mở rộng. Đối với các sự kiện đơn lẻ, trường này là không bắt buộc và biểu thị múi giờ tùy chỉnh cho thời điểm bắt đầu/kết thúc sự kiện. có thể ghi
status string Trạng thái của sự kiện. Không bắt buộc. Các giá trị có thể có là:
  • "confirmed" – Sự kiện đã được xác nhận. Đây là trạng thái mặc định.
  • "tentative" – Sự kiện này sẽ tạm thời được xác nhận.
  • "cancelled" – Sự kiện bị huỷ (đã xoá). Phương thức list (danh sách) chỉ trả về các sự kiện bị huỷ trong quá trình đồng bộ hoá gia tăng (khi syncToken hoặc updatedMin được chỉ định) hoặc nếu cờ showDeleted được đặt thành true. Phương thức get luôn trả về các kết quả này.

    Trạng thái đã huỷ thể hiện hai trạng thái khác nhau, tuỳ thuộc vào loại sự kiện:

    1. Các ngoại lệ bị hủy của một sự kiện định kỳ chưa bị hủy cho biết rằng bạn không nên hiển thị phiên bản này cho người dùng nữa. Ứng dụng cần lưu trữ các sự kiện này trong suốt thời gian diễn ra sự kiện định kỳ gốc.

      Các trường hợp ngoại lệ đã huỷ chỉ được đảm bảo có giá trị cho các trường id, recurringEventId và originalStartTime được điền sẵn. Các trường khác có thể trống.

    2. Tất cả các sự kiện bị huỷ khác biểu thị cho các sự kiện đã bị xoá. Ứng dụng nên xoá các bản sao đã đồng bộ hoá cục bộ của chúng. Những sự kiện bị huỷ như vậy cuối cùng sẽ biến mất, vì vậy đừng dựa vào chúng để sử dụng vô thời hạn.

      Các sự kiện đã xoá chỉ được đảm bảo điền sẵn trường id.

    Trên lịch của người tổ chức, các sự kiện đã bị huỷ sẽ tiếp tục hiển thị thông tin chi tiết về sự kiện (tóm tắt, vị trí, v.v.) để có thể khôi phục (bỏ xoá). Tương tự, các sự kiện mà người dùng được mời và sự kiện mà người dùng đã xoá theo cách thủ công sẽ tiếp tục cung cấp thông tin chi tiết. Tuy nhiên, các yêu cầu đồng bộ hoá gia tăng với showDeleted được đặt thành false sẽ không trả về những thông tin chi tiết này.

    Nếu một sự kiện thay đổi người tổ chức (ví dụ như thông qua thao tác di chuyển) và người tổ chức ban đầu không có trong danh sách người tham dự, thì sự kiện đó sẽ bị huỷ và chỉ có trường id đảm bảo sẽ được điền sẵn.

có thể ghi
summary string Tiêu đề sự kiện. có thể ghi
transparency string Liệu sự kiện có chặn thời gian trên lịch hay không. Không bắt buộc. Các giá trị có thể có là:
  • "opaque" – Giá trị mặc định. Sự kiện không chặn thời gian trên lịch. Điều này tương đương với việc đặt chế độ Hiển thị tôi ở trạng thái thành Bận trong giao diện người dùng Lịch.
  • "transparent" – Sự kiện không bị chặn thời gian trên lịch. Điều này tương đương với việc đặt chế độ Hiển thị tôi là thành Có sẵn trong giao diện người dùng Lịch.
 có thể ghi
visibility string Chế độ hiển thị của sự kiện. Không bắt buộc. Các giá trị có thể có là:
  • "default" – Sử dụng chế độ hiển thị mặc định cho các sự kiện trên lịch. Đây là giá trị mặc định.
  • "public" – Sự kiện là công khai và thông tin chi tiết về sự kiện sẽ hiển thị cho tất cả người đọc lịch.
  • "private" – Sự kiện là riêng tư và chỉ những người tham dự sự kiện mới có thể xem thông tin chi tiết về sự kiện.
  • "confidential" – Sự kiện là riêng tư. Giá trị này được cung cấp vì lý do tương thích.
 có thể ghi
workingLocationProperties nested object Dữ liệu sự kiện tại địa điểm làm việc. có thể ghi
workingLocationProperties.customLocation object Nếu có, hãy chỉ định rằng người dùng đang làm việc tại một vị trí tuỳ chỉnh. có thể ghi
workingLocationProperties.customLocation.label string Một nhãn bổ sung không bắt buộc để cung cấp thêm thông tin. có thể ghi
workingLocationProperties.homeOffice any value Nếu có, hãy chỉ định rằng người dùng đang làm việc tại nhà. có thể ghi
workingLocationProperties.officeLocation object Nếu có, hãy chỉ rõ rằng người dùng đang làm việc tại văn phòng. có thể ghi
workingLocationProperties.officeLocation.buildingId string Giá trị nhận dạng toà nhà (không bắt buộc). Mã này phải tham chiếu đến mã toà nhà trong cơ sở dữ liệu Tài nguyên của tổ chức. có thể ghi
workingLocationProperties.officeLocation.deskId string Giá trị nhận dạng không gian làm việc (không bắt buộc). có thể ghi
workingLocationProperties.officeLocation.floorId string Giá trị nhận dạng giá sàn không bắt buộc. có thể ghi
workingLocationProperties.officeLocation.floorSectionId string Giá trị nhận dạng mục giá sàn (không bắt buộc). có thể ghi
workingLocationProperties.officeLocation.label string Tên văn phòng được hiển thị trong các ứng dụng khách của Lịch trên web và dành cho thiết bị di động. Bạn nên tham chiếu tên toà nhà trong cơ sở dữ liệu Tài nguyên của tổ chức. có thể ghi
workingLocationProperties.type string Loại địa điểm làm việc. Các giá trị có thể có là:
  • "homeOffice" – Người dùng đang làm việc tại nhà.
  • "officeLocation" – Người dùng đang làm việc tại văn phòng.
  • "customLocation" – Người dùng đang làm việc tại một vị trí tuỳ chỉnh.
Mọi thông tin chi tiết đều được chỉ định trong trường phụ của tên đã chỉ định, nhưng trường này có thể bị thiếu nếu trống. Mọi trường khác sẽ bị bỏ qua.

Bắt buộc khi thêm các thuộc tính về địa điểm làm việc.

 có thể ghi

Phản hồi

Nếu thành công, phương thức này sẽ trả về một tài nguyên Sự kiện trong nội dung phản hồi.

Ví dụ

Lưu ý: Các đoạn mã mẫu của phương thức này không phải là ví dụ cho mọi ngôn ngữ lập trình được hỗ trợ (xem trang thông tin về các thư viện dùng cho ứng dụng để biết danh sách các ngôn ngữ được hỗ trợ).

Java

Dùng thư viện ứng dụng Java.

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Retrieve the event from the API
Event event = service.events().get("primary", "eventId").execute();

// Make a change
event.setSummary("Appointment at Somewhere");

// Update the event
Event updatedEvent = service.events().update("primary", event.getId(), event).execute();

System.out.println(updatedEvent.getUpdated());

Python

Dùng thư viện ứng dụng Python.

# First retrieve the event from the API.
event = service.events().get(calendarId='primary', eventId='eventId').execute()

event['summary'] = 'Appointment at Somewhere'

updated_event = service.events().update(calendarId='primary', eventId=event['id'], body=event).execute()

# Print the updated date.
print updated_event['updated']

PHP

Dùng thư viện ứng dụng PHP.

// First retrieve the event from the API.
$event = $service->events->get('primary', 'eventId');

$event->setSummary('Appointment at Somewhere');

$updatedEvent = $service->events->update('primary', $event->getId(), $event);

// Print the updated date.
echo $updatedEvent->getUpdated();

Ruby

Dùng thư viện ứng dụng Ruby.

event = client.get_event('primary', 'eventId')
event.summary = 'Appointment at Somewhere'
result = client.update_event('primary', event.id, event)
print result.updated

Hãy dùng thử!

Hãy sử dụng APIs Explorer (Trình khám phá API) bên dưới để gọi phương thức này trên dữ liệu trực tiếp và xem phản hồi.