MCP Tools Reference: sheetsmcp.googleapis.com

ابزار: update_values

مقادیر را در محدوده‌ای از صفحه‌گسترده تنظیم می‌کند.

با spreadsheets.values.update در REST API مطابقت دارد: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/update

طرحواره: - spreadsheet_id (رشته، الزامی): شناسه صفحه‌گسترده‌ای که باید به‌روز شود. - range (رشته، الزامی): نماد A1 مقادیر برای به‌روزرسانی (برای نمونه "Sheet1!A1:B2"). - values (آرایه آرایه‌ها، الزامی): آرایه دوبعدی مقادیر سلول. انواع مقدار پشتیبانی‌شده عبارت‌اند از: بولی، رشته، و عدد (شناور/صحیح).

نمونه کد زیر نحوه استفاده از curl برای فراخوانی ابزار update_values MCP را نشان می‌دهد.

درخواست 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
}'

طرح‌واره ورودی

UpdateValuesRequest

نمایش JSON 
{
  "spreadsheetId": string,
  "range": string,
  "values": [
    array
  ]
}
فیلدها
spreadsheetId

string

الزامی. شناسه صفحه‌گسترده برای به‌روزرسانی.
range

string

الزامی. نمانام A1 مقادیر برای به‌روزرسانی.
values[]

array (ListValue format)

الزامی. داده‌هایی که خوانده شده است یا قرار است نوشته شود. این آرایه‌ای از آرایه‌ها است، آرایه بیرونی نشان‌دهنده همه داده‌ها و هر آرایه درونی نشان‌دهنده یک ردیف است. هر عنصر در آرایه داخلی با یک سلول مطابقت دارد. انواع مقدار پشتیبانی‌شده عبارت‌اند از: بولی، رشته، و دوبرابر. از مقادیر تهی رد خواهد شد. برای تنظیم سلول روی مقدار خالی، مقدار رشته را روی رشته خالی تنظیم کنید.

ListValue

نمایش JSON 
{
  "values": [
    value
  ]
}
فیلدها
values[]

value (Value format)

فیلد تکراری مقادیر با نوع پویا.

مقدار

نمایش JSON 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
فیلدها
فیلد اتحادیه kind. نوع مقدار. ‫kind فقط می‌تواند یکی از موارد زیر باشد:
nullValue

null

نشان‌دهنده null در JSON است.
numberValue

number

نشان‌دهنده عدد JSON است. نباید NaN، Infinity، یا -Infinity باشد، زیرا در JSON پشتیبانی نمی‌شوند. این همچنین نمی‌تواند مقادیر بزرگ Int64 را نشان دهد، زیرا قالب JSON به‌طورکلی از آن‌ها در نوع عدد خود پشتیبانی نمی‌کند.
stringValue

string

نشان‌دهنده رشته JSON است.
boolValue

boolean

نشان‌دهنده مقدار بولی JSON (حرفی true یا false در JSON).
structValue

object (Struct format)

نشان‌دهنده شیء JSON است.
listValue

array (ListValue format)

نشان‌دهنده آرایه JSON است.

Struct

نمایش JSON 
{
  "fields": {
    string: value,
    ...
  }
}
فیلدها
fields

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

نقشه نامرتب مقادیر با نوع پویا.

شیئی حاوی فهرستی از "key": value جفت. مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

نمایش JSON 
{
  "key": string,
  "value": value
}
فیلدها
key

string
value

value (Value format)

NullValue

نشان‌دهنده null در JSON است.

‫NullValue نگهبان است و از شمارشی با فقط یک مقدار برای نشان دادن مقدار تهی برای اجتماع نوع Value استفاده می‌کند.

فیلدی از نوع NullValue با هر مقداری به‌جز 0 نامعتبر درنظر گرفته می‌شود. اکثر سریال‌سازهای ProtoJSON‏ Value را با null_value تنظیم‌شده به‌عنوان null در JSON صرف‌نظر از مقدار عدد صحیح منتشر می‌کنند و بنابراین به مقدار 0 تبدیل می‌شوند.

شمارشی‌ها
NULL_VALUE مقدار تهی.

طرح‌واره برونداد

نشان‌دهنده شیء JSON است.

نقشه مقدار-کلید بدون ترتیب که هدف آن به‌طور کامل گرفتن معنای شیء JSON است. این کار باعث می‌شود هر پیام‌واره JSON دلخواهی به‌عنوان فیلد پیام در قالب ProtoJSON تجزیه شود.

این نوع از دستورالعمل‌های RFC 8259 برای JSON قابل‌تعامل پیروی می‌کند: به‌ویژه این نوع نمی‌تواند مقادیر بزرگ Int64 یا اعداد NaN/Infinity را نشان دهد، زیرا قالب JSON به‌طورکلی از این مقادیر در نوع عدد خود پشتیبانی نمی‌کند.

اگر قصد ندارید JSON دلخواه را در پیامتان تجزیه کنید، بهتر است به‌جای استفاده از این نوع، از پیام تایپ‌شده سفارشی استفاده کنید.

Struct

نمایش JSON 
{
  "fields": {
    string: value,
    ...
  }
}
فیلدها
fields

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

نقشه نامرتب مقادیر با نوع پویا.

شیئی حاوی فهرستی از "key": value جفت. مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

نمایش JSON 
{
  "key": string,
  "value": value
}
فیلدها
key

string
value

value (Value format)

مقدار

نمایش JSON 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
فیلدها
فیلد اتحادیه kind. نوع مقدار. ‫kind فقط می‌تواند یکی از موارد زیر باشد:
nullValue

null

نشان‌دهنده null در JSON است.
numberValue

number

نشان‌دهنده عدد JSON است. نباید NaN، Infinity، یا -Infinity باشد، زیرا در JSON پشتیبانی نمی‌شوند. این همچنین نمی‌تواند مقادیر بزرگ Int64 را نشان دهد، زیرا قالب JSON به‌طورکلی از آن‌ها در نوع عدد خود پشتیبانی نمی‌کند.
stringValue

string

نشان‌دهنده رشته JSON است.
boolValue

boolean

نشان‌دهنده مقدار بولی JSON (حرفی true یا false در JSON).
structValue

object (Struct format)

نشان‌دهنده شیء JSON است.
listValue

array (ListValue format)

نشان‌دهنده آرایه JSON است.

ListValue

نمایش JSON 
{
  "values": [
    value
  ]
}
فیلدها
values[]

value (Value format)

فیلد تکراری مقادیر با نوع پویا.

NullValue

نشان‌دهنده null در JSON است.

‫NullValue نگهبان است و از شمارشی با فقط یک مقدار برای نشان دادن مقدار تهی برای اجتماع نوع Value استفاده می‌کند.

فیلدی از نوع NullValue با هر مقداری به‌جز 0 نامعتبر درنظر گرفته می‌شود. اکثر سریال‌سازهای ProtoJSON‏ Value را با null_value تنظیم‌شده به‌عنوان null در JSON صرف‌نظر از مقدار عدد صحیح منتشر می‌کنند و بنابراین به مقدار 0 تبدیل می‌شوند.

شمارشی‌ها
NULL_VALUE مقدار تهی.

حاشیه‌نویسی ابزار

گزارمان‌های ابزار برای توصیف خطر اولیه یک ابزار معین به کارخواهان MCP ارسال می‌شود. اکثر کارخواه‌ها این نشانه‌ها را به‌عنوان نامطمئن درنظر می‌گیرند، اما می‌توان از آن‌ها برای تصمیم‌گیری درباره زمان ارسال پیام‌واره تأیید به کاربر استفاده کرد.

به‌همراه رشته عنوان، نشان‌های بولی زیر به این صورت تعریف می‌شوند:

  • ‫readOnlyHint: اگر درست باشد، ابزار محیطش را تغییر نمی‌دهد. پیش‌فرض: نادرست.
  • ‫destructiveHint: اگر درست باشد، ابزار می‌تواند کنش‌های مخرب انجام دهد. اگر نادرست باشد، ابزار فقط می‌تواند کنش‌های افزودنی انجام دهد. پیش‌فرض: درست.
  • idempotentHint: اگر درست باشد، فراخوانی مکرر ابزار با همان آرگومان‌ها تأثیر اضافه‌ای بر محیط آن نخواهد داشت. پیش‌فرض: نادرست.
  • ‫openWorldHint: اگر درست باشد، ابزار می‌تواند با «دنیای باز» نهادهای خارجی تعامل داشته باشد. اگر نادرست باشد، ابزار فقط می‌تواند با نهادهای داخلی تعامل داشته باشد. برای مثال، ابزار جستجوی وب دنیای باز است، اما ابزار حافظه دنیای باز نیست.

راهنمایی مخرب: ❌ | راهنمایی خودتوان: ❌ | راهنمایی فقط خواندنی: ❌ | راهنمایی جهان باز: ✅

دوربین تفنگ مجوز

به یکی از محدوده‌های OAuth زیر نیاز دارد:

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