MCP Tools Reference: calendarmcp.googleapis.com

Công cụ: get_event

Trả về một sự kiện duy nhất từ một lịch nhất định.

Sử dụng công cụ này cho các truy vấn như:

  • Xem thông tin chi tiết về cuộc họp nhóm.
  • Cho tôi xem sự kiện có mã event123 trên lịch của tôi.

Ví dụ:

get_event(
            eventId='event123'
        )
        # Returns the event details for the event with id `event123` on the user's primary calendar.

Mẫu sau đây minh hoạ cách sử dụng curl để gọi công cụ get_event MCP.

Yêu cầu Curl 
curl --location 'https://calendarmcp.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "get_event",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Giản đồ đầu vào

GetEventRequest

Biểu diễn dưới dạng JSON 
{
  "eventId": string,

  "calendarId": string
}
Trường
eventId

string

Bắt buộc. Mã sự kiện cần lấy.

Trường nhóm _calendar_id.

_calendar_id chỉ có thể là một trong những trạng thái sau:
calendarId

string

Không bắt buộc. Mã lịch để lấy sự kiện. Theo mặc định, đây là lịch chính của người dùng.

Giản đồ đầu ra

Sự kiện

Biểu diễn dưới dạng JSON 
{
  "id": string,
  "status": string,
  "htmlLink": string,
  "created": string,
  "updated": string,
  "summary": string,
  "description": string,
  "location": string,
  "creator": {
    object (Principal)
  },
  "organizer": {
    object (Principal)
  },
  "start": {
    object (DateOrDateTime)
  },
  "end": {
    object (DateOrDateTime)
  },
  "recurrence": [
    string
  ],
  "recurringEventId": string,
  "originalStartTime": {
    object (DateOrDateTime)
  },
  "transparency": string,
  "visibility": string,
  "attendees": [
    {
      object (Attendee)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ]
}
Trường
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 được cung cấp phải tuân thủ 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 tính chất phân tán trên toàn cầu của hệ thống, 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 diễn ra của một sự kiện đều có mã nhận dạng khác nhau trong khi tất cả đều dùng chung cùng một icalUID.
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ỷ (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. Các ứng dụng nên lưu trữ những sự kiện này trong suốt thời gian diễn ra sự kiện định kỳ mẹ.Các trường hợp 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 đã bị xoá chỉ đảm bảo có trường mã nhận dạng được điền sẵn.

Trên lịch của người tổ chức, các sự kiện đã 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 (huỷ 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ỉ trường id được đảm bảo sẽ được điền sẵn.
htmlLink

string

Đường liên kết tuyệt đối đến sự kiện này trong giao diện người dùng web của Lịch Google. Chỉ đọc.
created

string

Thời gian tạo sự kiện (dưới dạng dấu thời gian được định dạng theo ISO 8601). Chỉ đọc.
updated

string

Thời gian sửa đổi gần đây nhất của dữ liệu sự kiện chính (dưới dạng dấu thời gian được định dạng theo ISO 8601). Việc cập nhật lời nhắc về sự kiện sẽ không làm thay đổi chế độ này. Chỉ đọc.
summary

string

Tiêu đề sự kiện.
description

string

Mô tả về sự kiện. Có thể chứa HTML. Không bắt buộc.
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.
creator

object (Principal)

Người tạo sự kiện. Chỉ đọc.
organizer

object (Principal)

Người tổ chức sự kiện. Nếu người tổ chức cũng là người tham dự, thì điều này sẽ được biểu thị bằng một mục riêng trong người tham dự, trong đó trường người tổ chức được đặt thành True. Chỉ đọc.
start

object (DateOrDateTime)

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.
end

object (DateOrDateTime)

Thời gian kết thúc (không bao gồm) của sự kiện. Đối với 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.
recurrence[]

string

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 bắt đầu và kết thúc. 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ỳ.
recurringEventId

string

Đối với một phiên bản của sự kiện định kỳ, đây là mã nhận dạng của sự kiện định kỳ mà phiên bản này thuộc về. Không thể thay đổi.
originalStartTime

object (DateOrDateTime)

Đối với một phiên bản của sự kiện định kỳ, đây là thời gian mà sự kiện này sẽ bắt đầu theo dữ liệu định kỳ trong sự kiện định kỳ được xác định bằng recurringEventId. Mã này xác định riêng biệt phiên bản trong chuỗi sự kiện định kỳ, ngay cả khi phiên bản đó được chuyển sang một thời gian khác. Không thể thay đổi.
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 trạng thái Hiển thị tôi là Đang bận trong giao diện người dùng Lịch.
  • transparent – Sự kiện này không chặn 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à có thể tham dự trong giao diện người dùng Lịch.
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 này là sự kiện 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 này là riêng tư. Giá trị này được cung cấp vì lý do tương thích.
attendees[]

object (Attendee)

Người tham dự sự kiện.
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 diễn ra cả ngày và lặp lại 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 cần tập trung.
  • fromGmail – 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.
conferenceUrl

string

Đường liên kết đến Google Meet của sự kiện.
colorId

string

Mã màu sự kiện (chuỗi 1 – 11):

  • 1: Oải hương
  • 2: Sage
  • 3: Nho
  • 4: Hồng hạc
  • 5: Chuối
  • 6: Cam
  • 7: Peacock
  • 8: Màu grafit
  • 9: Quả việt quất
  • 10: Húng quế
  • 11: Cà chua.

Trong Lịch Google, màu sắc của sự kiện hoạt động như các danh mục – bạn có thể đặt cho từng sự kiện hoặc từng chuỗi sự kiện. Người dùng có thể chỉ định nhãn tuỳ chỉnh cho màu sắc trong giao diện người dùng trên web (ví dụ: 1:1s, Break), nhưng API chỉ hiển thị mã nhận dạng dạng số chứ không hiển thị các nhãn đó. Chỉ ảnh hưởng đến chế độ xem lịch của riêng bạn – mỗi người tham dự sẽ kiểm soát màu sự kiện của riêng họ.
overrideReminders[]

object (Reminder)

Lời nhắc được xác định cho sự kiện này, ghi đè lời nhắc mặc định cho lịch. Nếu bạn không đặt, hệ thống sẽ sử dụng lời nhắc mặc định trên lịch.

Tổng

Biểu diễn dưới dạng JSON 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Trường
email

string

Địa chỉ email của người dùng chính (lịch).
displayName

string

Tên của hiệu trưởng (nếu có).
self

boolean

Liệu người dùng này có tương ứng với lịch mà bản sao của sự kiện này xuất hiện hay không. Chỉ đọc. Giá trị mặc định là False.

DateOrDateTime

Biểu diễn dưới dạng JSON 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Trường
date

string

Ngày ở định dạng ISO 8601 vào nửa đêm theo giờ UTC, chẳng hạn như 2019-11-20T00:00:00Z. Nếu bạn đặt trường này, thì bạn không được đặt date_time.
dateTime

string

Dấu thời gian được định dạng theo ISO 8601, chẳng hạn như 2019-11-20T08:19:06-07:00 hoặc 2019-11-20T08:19:06Z. Nếu bạn đặt trường này, thì bạn không được đặt date.
timeZone

string

Tên múi giờ TZDB (nếu có).

Người tham dự

Biểu diễn dưới dạng JSON 
{
  "id": string,
  "email": string,
  "displayName": string,
  "organizer": boolean,
  "self": boolean,
  "resource": boolean,
  "optionalAttendee": boolean,
  "responseStatus": string,
  "comment": string,
  "additionalGuests": integer
}
Trường
id

string

Mã hồ sơ của người tham dự (nếu có).
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ự. Đó phải là địa chỉ email hợp lệ theo RFC5322. Bắt buộc khi thêm người tham dự.
displayName

string

Tên của người tham dự (nếu có). Không bắt buộc.
organizer

boolean

Người tham dự có phải là người tổ chức sự kiện hay không. Chỉ đọc. Giá trị mặc định là False.
self

boolean

Liệu mục này có đại diện cho lịch mà bản sao của sự kiện này xuất hiện hay không. Chỉ đọc. Giá trị mặc định là False.
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.
optionalAttendee

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.
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 – 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.
comment

string

Bình luận phản hồi của người tham dự. Không bắt buộc.
additionalGuests

integer

Số lượng khách bổ sung. Không bắt buộc. Giá trị mặc định là 0.

Lời nhắc

Biểu diễn dưới dạng JSON 
{

  "method": string

  "minutes": integer
}
Trường

Trường nhóm _method.

_method chỉ có thể là một trong những trạng thái sau:
method

string

Bắt buộc. Cách lời nhắc được gửi đến người 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.

Trường nhóm _minutes.

_minutes chỉ có thể là một trong những trạng thái sau:
minutes

integer

Bắt buộc. Số phút trước khi lời nhắc được gửi.

Chú giải công cụ

Gợi ý mang tính phá hoại: ❌ | Gợi ý mang tính luỹ đẳng: ✅ | Gợi ý chỉ đọc: ✅ | Gợi ý về thế giới mở: ❌