MCP Tools Reference: sheetsmcp.googleapis.com

ابزار: insert_dimension

ردیف‌ها یا ستون‌هایی را در برگ در نمایه‌ای خاص درج می‌کند.

با «درخواست درج بُعد» در spreadsheets.batchUpdate REST API مطابقت دارد: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request

طرحواره: - spreadsheet_id (رشته، الزامی): شناسه صفحه‌گسترده‌ای که باید به‌روز شود. - sheet_id (عدد صحیح، الزامی): شناسه برگه‌ای که باید در آن درج شود. - dimension (رشته، الزامی): "ROWS" یا "COLUMNS". - start_index (عدد صحیح، الزامی): شاخص شروع درج (فراگیر) مبتنی بر ۰. - end_index (عدد صحیح، الزامی): نمایه پایانی مبتنی بر ۰ برای درج (انحصاری). - inherit_from_before (بولی، اختیاری): اینکه آیا دارایی‌های بُعد باید از ابعاد قبل (true) یا بعد (false) گسترش یابد.

نمونه کد زیر نحوه استفاده از curl برای فراخوانی ابزار insert_dimension 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": "insert_dimension",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

InsertDimensionRequest

نمایش JSON 
{
  "spreadsheetId": string,
  "sheetId": integer,
  "dimension": enum (Dimension),
  "startIndex": integer,
  "endIndex": integer,
  "inheritFromBefore": boolean
}
فیلدها
spreadsheetId

string

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

integer

الزامی. شناسه برگی که باید در آن درج شود.
dimension

enum (Dimension)

الزامی. ابعادی که باید درج شود.
startIndex

integer

الزامی. نمایه شروع مبتنی بر ۰ برای درج (فراگیر).
endIndex

integer

الزامی. نمایه پایانی مبتنی بر ۰ درج (انحصاری).
inheritFromBefore

boolean

اینکه آیا دارایی‌های بُعد باید از ابعاد قبل یا بعداز ابعاد تازه درج‌شده گسترش یابد. اگر می‌خواهید از ابعاد قبلی ارث ببرید درست است (در این صورت، شاخص شروع باید بزرگ‌تر از ۰ باشد)، و اگر می‌خواهید از ابعاد بعدی ارث ببرید نادرست است.

ابعاد

نشان می‌دهد که یک عملیات باید روی کدام بُعد اعمال شود.

شمارشی‌ها
DIMENSION_UNSPECIFIED مقدار پیش‌فرض، استفاده نکنید.
COLUMNS روی ستون‌های برگه عمل می‌کند.
ROWS روی ردیف‌های برگ کار می‌کند.

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

نشان‌دهنده شیء 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/spreadsheets