Events: insert

Tạo một sự kiện. Thử ngay.

Yêu cầu

Yêu cầu HTTP

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

Thông số

Tên thông số Giá trị Mô tả
Tham số đường dẫn
calendarId string Mã 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 vào lịch chính của người dùng hiện đang đăng nhập, hãy sử dụng từ khoá "primary".
Tham số truy vấn không bắt buộc
conferenceDataVersion integer Số phiên bản của dữ liệu hội nghị do ứ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 nội dung của sự kiện. Phiên bản 1 hỗ trợ việc sao chép ConferenceData cũng như việc tạo hội nghị mới bằng cách sử dụng trường createRequest của conferenceData. 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ần đưa vào phản hồi. Nếu có nhiều người tham dự hơn số lượng được chỉ định, thì chỉ người tham gia mới được trả về. Không bắt buộc.
sendNotifications boolean Không dùng nữa. Vui lòng sử dụng sendUpdates.

Có gửi thông báo về việc tạo sự kiện mới hay không. 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 Có gửi thông báo về việc tạo sự kiện mới hay không. Xin lưu ý rằng một số email có thể vẫn được gửi. Mặc định là false.

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 dùng Lịch Google.
  • "none": Không gửi thông báo.
supportsAttachments boolean Cho biết liệu ứng dụng API 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ó 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
https://www.googleapis.com/auth/calendar.app.created
https://www.googleapis.com/auth/calendar.events.owned

Để 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 một Tài nguyên Sự kiện có 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 (không bao gồm) 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 xuất hiện đầu tiên.
start nested object Thời gian bắt đầu (bao gồm cả) của sự kiện. Đối với sự kiện định kỳ, đây là thời gian bắt đầu của phiên bản đầu tiên.
Thuộc tính không bắt buộc
anyoneCanAddSelf boolean Liệu có ai có thể tự mời mình tham dự 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. writable
attachments[].fileUrl string Đường liên kết URL đến tệp đính kèm.

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

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

 writable
attendees[] list Người tham dự sự kiện. Hãy xem hướng dẫn Sự kiện có 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. Tài khoản dịch vụ cần sử dụng quyền uỷ quyền trên toàn miền để điền sẵn danh sách người tham dự. writable
attendees[].additionalGuests integer Số lượng khách bổ sung. Không bắt buộc. Giá trị mặc định là 0. writable
attendees[].comment string Bình luận phản hồi của người tham dự. Không bắt buộc. writable
attendees[].displayName string Tên của người tham dự (nếu có). Không bắt buộc. writable
attendees[].email string Địa chỉ email của người tham dự (nếu có). Bạn phải điền trường này khi thêm người tham dự. Đây phải là địa chỉ email hợp lệ theo RFC5322.

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

 writable
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 Người tham dự có phải là 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ể là:
  • "needsAction" – Người tham dự chưa phản hồi lời mời (nên dùng cho các sự kiện mới).
  • "declined" – Khách mời đã từ chối lời mời.
  • "tentative" – Khách mời đã chấp nhận lời mời (dự kiến).
  • "accepted" – Khách mời đã chấp nhận lời mời.
 có thể ghi
birthdayProperties nested object Dữ liệu về ngày sinh hoặc sự kiện đặc biệt. Được dùng nếu eventType là "birthday". Không thể thay đổi. có thể ghi
birthdayProperties.type string Loại sinh nhật hoặc sự kiện đặc biệt. Các giá trị có thể là:
  • "anniversary" – Một ngày kỷ niệm không phải là sinh nhật. Luôn có contact.
  • "birthday" – Sự kiện sinh nhật. Đây là giá trị mặc định.
  • "custom" – Một ngày đặc biệt có nhãn được chỉ định thêm trong trường customTypeName. Luôn có contact.
  • "other" – Một ngày đặc biệt không thuộc các danh mục khác và không có nhãn tuỳ chỉnh. Luôn có contact.
  • "self" – Sinh nhật của chính chủ sở hữu lịch. Không được có contact.
Calendar API chỉ hỗ trợ việc tạo sự kiện có loại "birthday". Bạn không thể thay đổi loại này sau khi tạo sự kiện.		 có thể ghi
colorId string Màu của sự kiện. Đây là một mã nhận dạng đề cập đế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ị, 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 hội nghị mới, 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 diễn ra cả ngày. có thể ghi
end.dateTime datetime Thời gian, dưới dạng giá trị ngày giờ kết hợp (được định dạng theo RFC3339). Bạn phải cung cấp độ lệch múi giờ, trừ phi bạn chỉ định rõ ràng múi giờ trong timeZone. có thể ghi
end.timeZone string Múi giờ mà thời gian được chỉ định. (Được định dạng dưới dạng tên trong Cơ sở dữ liệu múi giờ IANA, ví dụ: "Europe/Zurich".) Đối với sự kiện lặp lại, bạn phải điền trường này và chỉ định múi giờ mà trong đó sự kiện lặp lại được mở rộng. Đối với sự kiện diễn ra một lần, trường này là không bắt buộc và cho biết múi giờ tuỳ chỉnh cho thời gian bắt đầu/kết thúc sự kiện. có thể ghi
eventType string Loại cụ thể của sự kiện. Bạn không thể sửa đổi chế độ này sau khi tạo sự kiện. Các giá trị có thể là:
  • "birthday" – Một sự kiện đặc biệt kéo dài cả ngày và diễn ra hằng năm.
  • "default" – Sự kiện thông thường hoặc không được chỉ định thêm.
  • "focusTime" – Sự kiện thời gian tập trung.
  • "fromGmail" – Một sự kiện từ Gmail. Bạn không thể tạo loại sự kiện này.
  • "outOfOffice" – Sự kiện không có mặt tại văn phòng.
  • "workingLocation" – Sự kiện địa điểm làm việc.
 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 Các thuộc tính được dùng chung giữa các bản sao của sự kiện trên lịch của những người tham dự khác. có thể ghi
focusTimeProperties nested object Dữ liệu sự kiện 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ể là:
  • "icon" – Tiện ích này xuất hiện bên cạnh tiêu đề của sự kiện trong chế độ xem lịch.
  • "chip" – Tiện ích này sẽ xuất hiện khi người dùng nhấp vào sự kiện.
 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à một số nguyên lớn hơn 0. Không bắt buộc. Không dùng nữa. writable
gadget.preferences object Tùy chọn. writable
gadget.title string Tiêu đề của tiện ích. Không dùng nữa. writable
gadget.type string Loại của 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 những người tham dự không phải là 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 những người tham dự không phải là 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. writable
guestsCanSeeOtherGuests boolean Liệu những người tham dự không phải là người tổ chức có thể xem danh sách người tham dự sự kiện hay không. Không bắt buộc. Giá trị mặc định là True. có thể ghi
id string Giá trị nhận dạng không công khai của sự kiện. Khi tạo sự kiện mới (một lần hoặc định kỳ), bạn có thể chỉ định mã nhận dạng cho các sự kiện đó. Giá trị nhận dạng bạn cung cấp phải tuân theo các quy tắc sau:
  • các ký tự được phép trong mã nhận dạng là những ký tự được dùng trong phương thức mã hoá base32hex, tức là chữ cái thường a-v và chữ số 0-9, hãy xem phần 3.1.2 trong RFC2938
  • mã nhận dạng phải có độ dài từ 5 đến 1024 ký tự
  • mỗi lịch phải có một mã riêng biệt
Do hệ thống được phân phối trên toàn cầu, nên chúng tôi không thể đảm bảo rằng các xung đột về mã nhận dạng sẽ được phát hiện tại thời điểm tạo sự kiện. Để giảm thiểu nguy cơ xảy ra xung đột, bạn nên sử dụng một thuật toán UUID đã được thiết lập, chẳng hạn như thuật toán được mô tả trong RFC4122.

Nếu bạn không chỉ định mã nhận dạng, thì máy chủ sẽ tự động tạo mã nhận dạng.

Xin lưu ý rằng icalUID và id không giống nhau và bạn chỉ nên cung cấp một trong hai giá trị này khi tạo sự kiện. Một điểm khác biệt về ngữ nghĩa là trong các sự kiện định kỳ, tất cả các lần xuất hiện của một sự kiện đều có id riêng, trong khi tất cả đều dùng chung một icalUID.

 writable
location string Vị trí địa lý của sự kiện dưới dạng văn bản dạng 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 diễn ra cả ngày. writable
originalStartTime.dateTime datetime Thời gian, dưới dạng giá trị ngày giờ kết hợp (được định dạng theo RFC3339). Bạn phải cung cấp độ lệch múi giờ, trừ phi bạn chỉ định rõ ràng múi giờ trong timeZone. có thể ghi
originalStartTime.timeZone string Múi giờ mà thời gian được chỉ định. (Được định dạng dưới dạng tên trong Cơ sở dữ liệu múi giờ IANA, ví dụ: "Europe/Zurich".) Đối với sự kiện lặp lại, bạn phải điền trường này và chỉ định múi giờ mà trong đó sự kiện lặp lại được mở rộng. Đối với sự kiện diễn ra một lần, trường này là không bắt buộc và cho biết múi giờ tuỳ chỉnh cho thời gian bắt đầu/kết thúc sự kiện. writable
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. writable
recurrence[] list Danh sách các dòng RRULE, EXRULE, RDATE và EXDATE cho một sự kiện định kỳ, như được chỉ định trong RFC5545. Xin lưu ý rằng bạn không được phép sử dụng các dòng DTSTART và DTEND trong trường này; thời gian bắt đầu và kết thúc sự kiện được chỉ định trong các trường start và end. Trường này sẽ bị bỏ qua đối với các sự kiện diễn ra một lần hoặc các lần diễn ra của sự kiện định kỳ. writable
reminders.overrides[] list Nếu sự kiện không sử dụng lời nhắc mặc định, thì danh sách này sẽ liệt kê những lời nhắc dành riêng cho sự kiện đó. Nếu bạn không đặt lời nhắc, thì danh sách này sẽ cho biết rằng không 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. writable
reminders.overrides[].method string Phương thức mà lời nhắc này sử dụng. Các giá trị có thể 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 sự kiện bắt đầu mà lời nhắc sẽ kích hoạt. 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 iCalendar. có thể ghi
source.title string Tiêu đề của nguồn; ví dụ: tiêu đề của một trang web hoặc tiêu đề email. có thể ghi
source.url string URL của nguồn trỏ đến một tài nguyên. Giao thứ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 diễn ra cả ngày. writable
start.dateTime datetime Thời gian, dưới dạng giá trị ngày giờ kết hợp (được định dạng theo RFC3339). Bạn phải cung cấp độ lệch múi giờ, trừ phi bạn chỉ định rõ ràng múi giờ trong timeZone. có thể ghi
start.timeZone string Múi giờ mà thời gian được chỉ định. (Được định dạng dưới dạng tên trong Cơ sở dữ liệu múi giờ IANA, ví dụ: "Europe/Zurich".) Đối với sự kiện lặp lại, bạn phải điền trường này và chỉ định múi giờ mà trong đó sự kiện lặp lại được mở rộng. Đối với sự kiện diễn ra một lần, trường này là không bắt buộc và cho biết múi giờ tuỳ chỉnh cho thời gian 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ể là:
  • "confirmed" – Sự kiện đã được xác nhận. Đây là trạng thái mặc định.
  • "tentative" – Sự kiện đã được xác nhận tạm thời.
  • "cancelled" – Sự kiện bị huỷ (bị xoá). Phương thức list chỉ trả về các sự kiện đã huỷ khi đồng bộ hoá gia tăng (khi bạn chỉ định syncToken hoặc updatedMin) hoặc nếu bạn đặt cờ showDeleted thành true. Phương thức get luôn trả về các giá trị này.

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

    1. Các trường hợp ngoại lệ đã huỷ của một sự kiện định kỳ chưa huỷ cho biết rằng người dùng sẽ không còn thấy phiên bản này nữa. Ứng dụng nê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ỳ mẹ.

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

    2. Tất cả các sự kiện bị huỷ khác đều là sự kiện đã bị xoá. Khách hàng nên xoá các bản sao được đồng bộ hoá cục bộ. Những sự kiện bị huỷ như vậy sẽ biến mất theo thời gian, vì vậy, bạn không nên dựa vào việc chúng sẽ luôn có sẵn.

      Các sự kiện đã xoá chỉ đảm bảo được đ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ỷ vẫn hiển thị thông tin chi tiết về sự kiện (nội dung tóm tắt, vị trí, v.v.) để có thể khôi phục (xoá trạng thái đã xoá). Tương tự, những sự kiện mà người dùng được mời tham gia và đã xoá theo cách thủ công vẫn sẽ cung cấp thông tin chi tiết. Tuy nhiên, các yêu cầu đồng bộ hoá gia tăng có 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ụ: 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 được đảm bảo sẽ được điền sẵn.

có thể ghi
summary string Tiêu đề sự kiện. có thể ghi
transparency string 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ể là:
  • "opaque" – Giá trị mặc định. Sự kiện này sẽ 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ị trạng thái của tôi là thành Bận trong giao diện người dùng Lịch.
  • "transparent" – Sự kiện này không chiếm thời gian trên lịch. Điều này tương đương với việc đặt trạng thái Hiển thị tôi là thành Rảnh trong giao diện người dùng Lịch.
 writable
visibility string Chế độ hiển thị của sự kiện. Không bắt buộc. Các giá trị có thể 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 ở chế độ công khai và tất cả người đọc lịch đều có thể xem thông tin chi tiết về sự kiện.
  • "private" – Sự kiện là riêng tư và chỉ 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 này 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 về đị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. writable
workingLocationProperties.customLocation.label string Nhãn bổ sung không bắt buộc để biết thêm thông tin. writable
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ỉ định 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 không bắt buộc của toà nhà. Mã này phải tham chiếu đến mã nhận dạng 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 bàn (không bắt buộc). có thể ghi
workingLocationProperties.officeLocation.floorId string Giá trị nhận dạng sàn (không bắt buộc). có thể ghi
workingLocationProperties.officeLocation.floorSectionId string Mã nhận dạng phần sàn (không bắt buộc). có thể ghi
workingLocationProperties.officeLocation.label string Tên văn phòng xuất hiện trong ứng dụng Lịch trên web và thiết bị di động. Bạn nên tham khảo 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ể 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 một trường phụ có tên được chỉ định, nhưng trường này có thể bị thiếu nếu trống. Mọi trường khác đều bị bỏ qua.

Bắt buộc khi thêm thuộc tính đị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.

Hãy dùng thử!

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