MCP Tools Reference: sheetsmcp.googleapis.com

Công cụ: update_values

Đặt giá trị trong một dải ô của bảng tính.

Tương ứng với spreadsheets.values.update trong API REST: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/update

Giản đồ: – spreadsheet_id (chuỗi, bắt buộc): Mã nhận dạng của bảng tính cần cập nhật. – range (chuỗi, bắt buộc): Ký hiệu A1 của các giá trị cần cập nhật (ví dụ: "Sheet1!A1:B2"). – values (mảng của mảng, bắt buộc): Mảng 2D của các giá trị ô. Các loại giá trị được hỗ trợ là: boolean, chuỗi và số (float/int).

Mã mẫu sau đây cho biết cách sử dụng curl để gọi công cụ MCP update_values.

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

Giản đồ đầu vào

UpdateValuesRequest

Biểu diễn dưới dạng JSON 
{
  "spreadsheetId": string,
  "range": string,
  "values": [
    array
  ]
}
Trường
spreadsheetId

string

Bắt buộc. Mã của bảng tính cần cập nhật.
range

string

Bắt buộc. Ký hiệu A1 của các giá trị cần cập nhật.
values[]

array (ListValue format)

Bắt buộc. Dữ liệu đã được đọc hoặc sẽ được ghi. Đây là một mảng gồm các mảng, trong đó mảng bên ngoài đại diện cho tất cả dữ liệu và mỗi mảng bên trong đại diện cho một hàng. Mỗi mục trong mảng bên trong tương ứng với một ô. Các loại giá trị được hỗ trợ là: bool, string và double. Các giá trị rỗng sẽ bị bỏ qua. Để đặt một ô thành giá trị trống, hãy đặt giá trị chuỗi thành chuỗi trống.

ListValue

Biểu diễn dưới dạng JSON 
{
  "values": [
    value
  ]
}
Trường
values[]

value (Value format)

Trường lặp lại của các giá trị được nhập động.

Giá trị

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

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
Trường
Trường nhóm kind. Loại giá trị. kind chỉ có thể là một trong những trạng thái sau:
nullValue

null

Đại diện cho một null JSON.
numberValue

number

Biểu thị một số JSON. Không được là NaN, Infinity hoặc -Infinity vì JSON không hỗ trợ các giá trị này. Điều này cũng không thể biểu thị các giá trị Int64 lớn, vì định dạng JSON thường không hỗ trợ các giá trị này trong kiểu số.
stringValue

string

Biểu thị một chuỗi JSON.
boolValue

boolean

Biểu thị một boolean JSON (true hoặc false giá trị cố định trong JSON).
structValue

object (Struct format)

Đại diện cho một đối tượng JSON.
listValue

array (ListValue format)

Biểu thị một mảng JSON.

Cấu trúc

Biểu diễn dưới dạng JSON 
{
  "fields": {
    string: value,
    ...
  }
}
Trường
fields

map (key: string, value: value (Value format))

Bản đồ không theo thứ tự của các giá trị được nhập động.

Một đối tượng chứa danh sách các cặp "key": value. Ví dụ: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

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

string
value

value (Value format)

NullValue

Đại diện cho một null JSON.

NullValue là một sentinel, sử dụng enum chỉ có một giá trị để biểu thị giá trị rỗng cho hợp kiểu Value.

Trường thuộc loại NullValue có giá trị khác với 0 được coi là không hợp lệ. Hầu hết các trình chuyển đổi tuần tự ProtoJSON sẽ phát ra một Value có null_value được đặt làm JSON null bất kể giá trị số nguyên, và do đó sẽ khứ hồi thành giá trị 0.

Enum
NULL_VALUE Giá trị rỗng.

Giản đồ đầu ra

UpdateValuesResponse

Biểu diễn dưới dạng JSON 
{
  "content": {
    object
  }
}
Trường
content

object (Struct format)

Phản hồi spreadsheets.values.update, ở định dạng JSON của API Trang tính, cộng với trường status.

Cấu trúc

Biểu diễn dưới dạng JSON 
{
  "fields": {
    string: value,
    ...
  }
}
Trường
fields

map (key: string, value: value (Value format))

Bản đồ không theo thứ tự của các giá trị được nhập động.

Một đối tượng chứa danh sách các cặp "key": value. Ví dụ: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

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

string
value

value (Value format)

Giá trị

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

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
Trường
Trường nhóm kind. Loại giá trị. kind chỉ có thể là một trong những trạng thái sau:
nullValue

null

Đại diện cho một null JSON.
numberValue

number

Biểu thị một số JSON. Không được là NaN, Infinity hoặc -Infinity vì JSON không hỗ trợ các giá trị này. Điều này cũng không thể biểu thị các giá trị Int64 lớn, vì định dạng JSON thường không hỗ trợ các giá trị này trong kiểu số.
stringValue

string

Biểu thị một chuỗi JSON.
boolValue

boolean

Biểu thị một boolean JSON (true hoặc false giá trị cố định trong JSON).
structValue

object (Struct format)

Đại diện cho một đối tượng JSON.
listValue

array (ListValue format)

Biểu thị một mảng JSON.

ListValue

Biểu diễn dưới dạng JSON 
{
  "values": [
    value
  ]
}
Trường
values[]

value (Value format)

Trường lặp lại của các giá trị được nhập động.

NullValue

Đại diện cho một null JSON.

NullValue là một sentinel, sử dụng enum chỉ có một giá trị để biểu thị giá trị rỗng cho hợp kiểu Value.

Trường thuộc loại NullValue có giá trị khác với 0 được coi là không hợp lệ. Hầu hết các trình chuyển đổi tuần tự ProtoJSON sẽ phát ra một Value có null_value được đặt làm JSON null bất kể giá trị số nguyên, và do đó sẽ khứ hồi thành giá trị 0.

Enum
NULL_VALUE Giá trị rỗng.

Chú thích về công cụ

Chú thích về công cụ được gửi đến ứng dụng MCP để mô tả rủi ro cơ bản của một công cụ nhất định. Hầu hết ứng dụng đều coi những gợi ý này là không đáng tin cậy, nhưng có thể dùng chúng để quyết định thời điểm gửi lời nhắc xác nhận cho người dùng.

Cùng với chuỗi tiêu đề, các gợi ý boolean sau đây được xác định như sau:

  • readOnlyHint: Nếu đúng, công cụ sẽ không sửa đổi môi trường của nó. Mặc định: false.
  • destructiveHint: Nếu đúng, thì công cụ có thể thực hiện các hành động có tính huỷ diệt. Nếu là false, thì công cụ chỉ có thể thực hiện các hành động bổ sung. Mặc định: true.
  • idempotentHint: Nếu đúng, thì việc gọi công cụ nhiều lần với cùng một đối số sẽ không có thêm hiệu ứng nào đối với môi trường của công cụ. Mặc định: false.
  • openWorldHint: Nếu đúng, thì công cụ có thể tương tác với "thế giới mở" của các thực thể bên ngoài. Nếu là false, thì công cụ chỉ có thể tương tác với các thực thể nội bộ. Ví dụ: công cụ tìm kiếm trên web sẽ là công cụ thế giới mở, còn công cụ ghi nhớ sẽ không phải là công cụ thế giới mở.

Gợi ý về hành động huỷ diệt: ❌ | Gợi ý về hành động không thay đổi giá trị: ❌ | Gợi ý về hành động chỉ đọc: ❌ | Gợi ý về hành động thế giới mở: ✅

Phạm vi cấp phép

Yêu cầu một trong các phạm vi OAuth sau:

  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets