MCP Tools Reference: sheetsmcp.googleapis.com

ابزار: update_spreadsheet

یک یا چند به‌روزرسانی را در صفحه‌گسترده اعمال می‌کند.

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

فهرست به‌روزرسانی‌های ممکن عبارت است از:

  • ‫updateSpreadsheetProperties: ویژگی‌های صفحه‌گسترده را به‌روز می‌کند. طرح‌واره:
  • ‫properties (شیء، الزامی): دارایی‌های صفحه‌گسترده برای به‌روزرسانی ({"title": string, "locale": string, "timeZone": string}).
  • fields (رشته، الزامی): پوشش فیلد ویژگی‌هایی که باید به‌روزرسانی شوند (برای نمونه، "title" یا "*").
  • ‫updateSheetProperties: ویژگی‌های برگ را به‌روزرسانی می‌کند. طرح‌واره:
  • ‫properties (شیء، الزامی): خصوصیات برگ ({"sheetId": int, "title": string, "index": int, "gridProperties": {"rowCount": int, "columnCount": int, "frozenRowCount": int, "frozenColumnCount": int, "hideGridlines": bool}, "hidden": bool, "tabColorStyle": {"rgbColor": {"red": float, "green": float, "blue": float}}}).
  • ‫fields (رشته، الزامی): پوشش فیلد دارایی‌ها برای به‌روزرسانی (برای نمونه، "title"، "gridProperties.frozenRowCount").
  • updateDimensionProperties: خصوصیات ابعاد را به‌روزرسانی می‌کند (برای نمونه، ارتفاع ردیف یا عرض ستون). طرح‌واره:
  • ‫range (شیء، الزامی): محدوده بُعد ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • ‫properties (شیء، الزامی): دارایی‌های بُعد ({"pixelSize": int, "hiddenByUser": bool}).
  • ‫fields (رشته، الزامی): پوشش فیلد دارایی‌ها برای به‌روزرسانی (برای نمونه، "pixelSize").
  • ‫updateNamedRange: محدوده نام‌گذاری‌شده‌ای را به‌روزرسانی می‌کند. طرح‌واره:
  • ‫namedRange (شیء، الزامی): تعریف محدوده نام‌گذاری‌شده ({"namedRangeId": string, "name": string, "range": {"sheetId": int, "startRowIndex": int, "endRowIndex": int, "startColumnIndex": int, "endColumnIndex": int}}).
  • fields (رشته، الزامی): پوشش فیلد فیلدهایی که باید به‌روزرسانی شوند (برای نمونه "name,range" یا "*").
  • ‫repeatCell: یک سلول را در سراسر یک محدوده تکرار می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده جدولی که داده/قالب‌بندی سلول در آن اعمال می‌شود ({"sheetId": int, "startRowIndex": int, "endRowIndex": int, "startColumnIndex": int, "endColumnIndex": int}).
  • ‫cell (شیء، الزامی): داده‌های سلولی ({"userEnteredValue": {"stringValue": str, "numberValue": float, "formulaValue": str}, "userEnteredFormat": {"textFormat": {"bold": bool, "italic": bool, "fontSize": int}, "backgroundColorStyle": {"rgbColor": {"red": float, "green": float, "blue": float}}, "horizontalAlignment": "LEFT"|"CENTER"|"RIGHT", "wrapStrategy": "WRAP"|"CLIP"|"OVERFLOW_CELL"}}).
  • fields (رشته، الزامی): پوشش فیلد فیلدهای سلول برای به‌روزرسانی (برای نمونه "userEnteredFormat.textFormat.bold" یا "userEnteredValue").
  • ‫addNamedRange: محدوده نام‌گذاری‌شده‌ای را اضافه می‌کند. طرح‌واره:
  • ‫namedRange (شیء، الزامی): محدوده نام‌گذاری‌شده برای افزودن ({"namedRangeId": string (optional), "name": string, "range": {"sheetId": int, "startRowIndex": int, "endRowIndex": int, "startColumnIndex": int, "endColumnIndex": int}}).
  • deleteNamedRange: محدوده نام‌گذاری‌شده‌ای را براساس شناسه‌اش حذف می‌کند. طرح‌واره:
  • ‫namedRangeId (رشته، الزامی): شناسه محدوده نام‌گذاری‌شده برای حذف.
  • ‫addSheet: برگه‌ای اضافه می‌کند. طرح‌واره:
  • ‫properties (شیء، اختیاری): مشخصه‌های برگ ({"title": string, "sheetId": int (optional), "index": int (optional), "gridProperties": {"rowCount": int, "columnCount": int}}).
  • ‫deleteSheet: برگه‌ای را حذف می‌کند. طرح‌واره:
  • sheetId (عدد صحیح، الزامی): شناسه برگ برای حذف.
  • autoFill: براساس داده‌های موجود، داده‌های بیشتری را به‌طور خودکار تکمیل می‌کند. طرح‌واره:
  • ‫range (شیء، اختیاری): محدوده برای بررسی و پر کردن ({"sheetId": int, "startRowIndex": int, "endRowIndex": int, "startColumnIndex": int, "endColumnIndex": int}).
  • ‫sourceAndDestination (شیء، اختیاری): منبع صریح و طول پر کردن ({"source": GridRange, "dimension": "ROWS"|"COLUMNS", "fillLength": int}).
  • ‫useAlternateSeries (بولی، اختیاری): اینکه از مجموعه جایگزین استفاده شود یا نه.
  • cutPaste: داده‌ها را از یک ناحیه برش می‌دهد و در ناحیه دیگری جای‌گذاری می‌کند. طرح‌واره:
  • ‫source (شیء، الزامی): محدوده شبکه منبع.
  • ‫destination (شیء، الزامی): مختصات مقصد در بالا سمت راست ({"sheetId": int, "rowIndex": int, "columnIndex": int}).
  • ‫pasteType (رشته، اختیاری): "PASTE_NORMAL"،‏ "PASTE_VALUES"،‏ "PASTE_FORMAT"،‏ "PASTE_NO_BORDERS"،‏ "PASTE_FORMULA".
  • ‫copyPaste: داده‌ها را از یک ناحیه کپی می‌کند و در ناحیه‌ای دیگر جای‌گذاری می‌کند. طرح‌واره:
  • ‫source (شیء، الزامی): محدوده شبکه منبع.
  • ‫destination (شیء، الزامی): محدوده جدول مقصد.
  • ‫pasteType (رشته، اختیاری): "PASTE_NORMAL"،‏ "PASTE_VALUES"،‏ "PASTE_FORMAT"،‏ "PASTE_NO_BORDERS"،‏ "PASTE_FORMULA".
  • ‫pasteOrientation (رشته، اختیاری): "NORMAL" یا "TRANSPOSE".
  • ‫mergeCells: سلول‌ها را با هم ادغام می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده شبکه برای ادغام.
  • ‫mergeType (رشته، الزامی): "MERGE_ALL"،‏ "MERGE_COLUMNS"، یا "MERGE_ROWS".
  • ‫unmergeCells: سلول‌های ادغام‌شده را از ادغام درمی‌آورد. طرح‌واره:
  • range (شیء، الزامی): محدوده جدولی که همه سلول‌ها در آن ادغام می‌شوند.
  • ‫updateBorders: حاشیه‌های محدوده سلول‌ها را به‌روز می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده صفحه گسترده برای به‌روزرسانی حاشیه‌ها.
  • ‫top / bottom / left / right / innerHorizontal / innerVertical (شیء، اختیاری): سبک حاشیه ({"style": "SOLID"|"DASHED"|"DOTTED"|"DOUBLE"|"NONE", "width": int, "colorStyle": {"rgbColor": {"red": float, "green": float, "blue": float}}}).
  • ‫updateCells: چندین سلول را به‌طور هم‌زمان به‌روزرسانی می‌کند. طرح‌واره:
  • مساحت (دقیقاً یک مورد الزامی است):
    • ‫start (شیء): مختصات بالا سمت چپ ({"sheetId": int, "rowIndex": int, "columnIndex": int}).
    • ‫range (شیء): محدوده جدول.
  • ‫rows (آرایه RowData، الزامی): ردیف‌های سلول ([{"values": [{"userEnteredValue": {"stringValue": str, "numberValue": float, "formulaValue": str}}]}]).
  • fields (رشته، الزامی): پوشش فیلد فیلدهای سلول برای به‌روزرسانی (برای نمونه "userEnteredValue" یا "userEnteredFormat").
  • ‫addFilterView: نمای فیلتر را اضافه می‌کند. طرح‌واره:
  • ‫filter (شیء، الزامی): تعریف نمای فیلتر ({"title": string, "range": GridRange, "criteria": map, "sortSpecs": list}).
  • ‫appendCells: سلول‌ها را پس‌از آخرین ردیف دارای داده در برگ پیوست می‌کند. طرح‌واره:
  • ‫sheetId (عدد صحیح، الزامی): شناسه برگ برای پیوست کردن داده‌ها به آن.
  • ‫rows (آرایه RowData، الزامی): ردیف‌های داده برای پیوست کردن.
  • ‫fields (رشته، الزامی): پوشش فیلد (برای نمونه "userEnteredValue").
  • ‫clearBasicFilter: فیلتر پایه را در برگ پاک می‌کند. طرح‌واره:
  • sheetId (عدد صحیح، الزامی): شناسه برگ که فیلتر پایه در آن پاک شود.
  • ‫deleteDimension: ردیف‌ها یا ستون‌ها را در برگ حذف می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده بُعد برای حذف کردن ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • ‫deleteEmbeddedObject: شیء جاسازی‌شده (برای نمونه، نمودار، تصویر) را در برگه‌ای حذف می‌کند. طرح‌واره:
  • objectId (عدد صحیح، الزامی): شناسه شیء جاسازی‌شده برای حذف.
  • ‫deleteFilterView: نمای فیلتر را از برگ حذف می‌کند. طرح‌واره:
  • ‫filterId (عدد صحیح، الزامی): شناسه نمای فیلتر برای حذف کردن.
  • ‫duplicateFilterView: نمای فیلتر را تکرار می‌کند. طرح‌واره:
  • ‫filterId (عدد صحیح، الزامی): شناسه نمای فیلتر برای تکرار کردن.
  • ‫duplicateSheet: برگه‌ای را تکثیر می‌کند. طرح‌واره:
  • ‫sourceSheetId (عدد صحیح، الزامی): شناسه برگ برای تکثیر.
  • ‫insertSheetIndex (عدد صحیح، اختیاری): نمایه مبتنی بر صفر که برگ جدید باید در آن درج شود.
  • ‫newSheetId (عدد صحیح، اختیاری): شناسه برگ جدید.
  • ‫newSheetName (رشته، اختیاری): نام برگ جدید.
  • findReplace: رخدادهای نوشتاری را با نوشتار دیگر پیدا و جایگزین می‌کند. طرح‌واره:
  • ‫find (رشته، الزامی): مقدار برای جستجو.
  • ‫replacement (رشته، الزامی): مقدار جایگزین.
  • حوزه (دقیقاً یک مورد الزامی است):
    • ‫range (شیء): محدوده جدول.
    • ‫sheetId (عدد صحیح): شناسه برگ.
    • ‫allSheets (منطقی): true برای جستجوی همه برگه‌ها.
  • ‫matchCase / matchEntireCell / searchByRegex / includeFormulas (منطقی، اختیاری).
  • ‫insertDimension: ردیف‌ها یا ستون‌های جدیدی را در برگ درج می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده بُعد برای درج ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • inheritFromBefore (منطقی، اختیاری): true برای به‌ارث بردن قالب‌بندی از ردیف/ستون قبلی.
  • ‫insertRange: سلول‌های جدیدی را در برگ درج می‌کند و سلول‌های موجود را جابه‌جا می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده جدولی برای درج سلول‌ها در آن.
  • ‫shiftDimension (رشته، الزامی): "ROWS" یا "COLUMNS".
  • ‫moveDimension: ردیف‌ها یا ستون‌ها را به مکان دیگری در برگ جابه‌جا می‌کند. طرح‌واره:
  • ‫source (شیء، الزامی): محدوده بُعد منبع ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • ‫destinationIndex (عدد صحیح، الزامی): شاخص مقصد مبنا صفر.
  • ‫updateEmbeddedObjectPosition: موقعیت شیء جاسازی‌شده (برای نمونه، نمودار، تصویر) را به‌روز می‌کند. طرح‌واره:
  • ‫objectId (عدد صحیح، الزامی): شناسه شیء جاسازی‌شده.
  • ‫newPosition (شیء، الزامی): موقعیت جدید ({"overlayPosition": {"anchorCell": {"sheetId": int, "rowIndex": int, "columnIndex": int}, "widthPixels": int, "heightPixels": int}}).
  • ‫fields (رشته، الزامی): پوشش فیلد (برای نمونه "overlayPosition.anchorCell").
  • pasteData: داده‌ها (HTML یا جداشده) را در برگ می‌چسباند. طرح‌واره:
  • ‫coordinate (شیء، الزامی): مختصات بالا سمت راست ({"sheetId": int, "rowIndex": int, "columnIndex": int}).
  • ‫data (رشته، الزامی): نوشتار محدودشده یا داده‌های HTML.
  • ‫delimiter (رشته، اختیاری) یا html (منطقی، اختیاری).
  • ‫type (رشته، اختیاری): "PASTE_NORMAL"، "PASTE_VALUES"، و غیره
  • ‫textToColumns: ستون نوشتار را به چند ستون نوشتار تبدیل می‌کند. طرح‌واره:
  • ‫source (شیء، الزامی): محدوده شبکه تک‌ستونی.
  • ‫delimiterType (رشته، الزامی): "COMMA"،‏ "SEMICOLON"،‏ "PERIOD"،‏ "SPACE"،‏ "CUSTOM"،‏ "AUTODETECT".
  • ‫delimiter (رشته، اختیاری): نویسه جداکننده وقتی delimiterType برابر با "CUSTOM" است.
  • updateFilterView: ویژگی‌های نمای فیلتر را به‌روز می‌کند. طرح‌واره:
  • ‫filter (شیء، الزامی): تعریف نمای فیلتر شامل filterViewId.
  • fields (رشته، الزامی): پوشش فیلد (برای نمونه "title,criteria" یا "*").
  • ‫deleteRange: محدوده‌ای از سلول‌ها را از برگ حذف می‌کند و سلول‌های باقی‌مانده را جابه‌جا می‌کند. طرح‌واره:
  • range (object، الزامی): محدوده جدولی برای حذف کردن.
  • ‫shiftDimension (رشته، الزامی): "ROWS" یا "COLUMNS".
  • ‫appendDimension: ابعاد را به انتهای برگ اضافه می‌کند. طرح‌واره:
  • ‫sheetId (عدد صحیح، الزامی): شناسه برگ.
  • ‫dimension (رشته، الزامی): "ROWS" یا "COLUMNS".
  • ‫length (عدد صحیح، الزامی): تعداد ردیف‌ها یا ستون‌هایی که باید اضافه شود.
  • addConditionalFormatRule: قانون قالب‌بندی شرطی جدیدی اضافه می‌کند. طرح‌واره:
  • ‫rule (شیء، الزامی): قانون قالب‌بندی مشروط ({"ranges": [GridRange], "booleanRule": {"condition": {"type": "NUMBER_GREATER_THAN_EQ"|"TEXT_CONTAINS"|..., "values": [{"userEnteredValue": string}]}, "format": CellFormat}, "gradientRule": {...}}).
  • ‫index (عدد صحیح، اختیاری): نمایه مبتنی بر صفر که قانون باید در آن درج شود.
  • ‫updateConditionalFormatRule: قانون قالب‌بندی شرطی موجود را به‌روزرسانی می‌کند. طرح‌واره:
  • ‫rule (شیء، الزامی): قانون قالب‌بندی شرطی جدید.
  • نمایه / شناسه قانون (یکی الزامی است):
    • ‫index (عدد صحیح): شاخص صفرمبنای قانون.
    • sheetId (عدد صحیح): شناسه برگ درصورت به‌روزرسانی براساس نمایه برگ.
  • newIndex (عدد صحیح، اختیاری): نمایه جدید برای انتقال قانون.
  • deleteConditionalFormatRule: قانون قالب‌بندی شرطی موجود را حذف می‌کند. طرح‌واره:
  • index (عدد صحیح، الزامی): نمایه مبتنی بر صفر قانون برای حذف.
  • ‫sheetId (عدد صحیح، الزامی): شناسه برگ قانون.
  • ‫sortRange: داده‌ها را در محدوده مرتب می‌کند. طرح‌واره:
  • range (شیء، الزامی): محدوده جدول برای مرتب کردن.
  • sortSpecs (آرایه SortSpec، الزامی): مشخصات مرتب‌سازی ([{"dimensionIndex": int, "sortOrder": "ASCENDING"|"DESCENDING"}]).
  • setDataValidation: اعتبارسنجی داده را برای یک یا چند سلول تنظیم می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده جدول.
  • ‫rule (شیء، اختیاری): قانون اعتبارسنجی ({"condition": {"type": "ONE_OF_LIST"|"NUMBER_BETWEEN"|..., "values": [{"userEnteredValue": string}]}, "strict": bool, "showCustomUi": bool}). اگر حذف شود، اعتبارسنجی پاک می‌شود.
  • ‫setBasicFilter: فیلتر پایه را روی برگ تنظیم می‌کند. طرح‌واره:
  • ‫filter (شیء، الزامی): تعریف فیلتر پایه ({"range": GridRange, "criteria": map, "sortSpecs": list}).
  • ‫addProtectedRange: محدوده محافظت‌شده‌ای را اضافه می‌کند. طرح‌واره:
  • ‫protectedRange (شیء، الزامی): تعریف محدوده محافظت‌شده ({"range": GridRange, "description": string, "warningOnly": bool, "editors": {"users": [string]}}).
  • ‫updateProtectedRange: محدوده محافظت‌شده‌ای را به‌روزرسانی می‌کند. طرح‌واره:
  • ‫protectedRange (شیء، الزامی): تعریف محدوده محافظت‌شده با protectedRangeId.
  • fields (رشته، الزامی): پوشش فیلد (برای نمونه "description,warningOnly" یا "*").
  • ‫deleteProtectedRange: محدوده محافظت‌شده‌ای را حذف می‌کند. طرح‌واره:
  • ‫protectedRangeId (عدد صحیح، الزامی): شناسه محدوده محافظت‌شده برای حذف.
  • autoResizeDimensions: به‌طور خودکار یک یا چند بُعد را براساس محتوای سلول تغییر اندازه می‌دهد. طرح‌واره:
  • ‫dimensions (شیء، الزامی): محدوده بُعد ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • ‫addChart: نموداری اضافه می‌کند. طرح‌واره:
  • ‫chart (شیء، الزامی): تعریف نمودار ({"spec": {"title": string, "basicChart": {"chartType": "COLUMN"|"BAR"|"LINE"|"PIE"|"COMBO"|"SCATTER", "legendPosition": string, "axis": list, "domains": list, "series": list}}, "position": {"overlayPosition": {"anchorCell": {"sheetId": int, "rowIndex": int, "columnIndex": int}}}}).
  • ‫updateChartSpec: مشخصات نمودار را به‌روزرسانی می‌کند. طرح‌واره:
  • chartId (عدد صحیح، الزامی): شناسه نمودار.
  • ‫spec (شیء، الزامی): مشخصات جدول جدید.
  • ‫updateBanding: محدوده نواری را به‌روزرسانی می‌کند. طرح‌واره:
  • ‫bandedRange (شیء، الزامی): تعریف محدوده نواری با bandedRangeId.
  • ‫fields (رشته، الزامی): پوشش فیلد.
  • ‫addBanding: محدوده نواری جدیدی اضافه می‌کند. طرح‌واره:
  • ‫bandedRange (شیء، الزامی): تعریف محدوده نواری ({"range": GridRange, "rowProperties": {"headerColorStyle": ColorStyle, "firstBandColorStyle": ColorStyle, "secondBandColorStyle": ColorStyle}}).
  • ‫deleteBanding: محدوده نواری را برمی‌دارد. طرح‌واره:
  • bandedRangeId (عدد صحیح، الزامی): شناسه محدوده دسته‌بندی‌شده برای حذف.
  • createDeveloperMetadata: فراداده توسعه‌دهنده جدیدی ایجاد می‌کند. طرح‌واره:
  • ‫developerMetadata (شیء، الزامی): تعریف فراداده ({"metadataKey": string, "metadataValue": string, "location": {"locationType": "ROW"|"COLUMN"|"SHEET"|"SPREADSHEET", "sheetId": int}, "visibility": "DOCUMENT"|"PROJECT"}).
  • updateDeveloperMetadata: ورودی فراداده توسعه‌دهنده موجود را به‌روزرسانی می‌کند. طرح‌واره:
  • dataFilters (آرایه DataFilter، الزامی): فیلترهایی برای انتخاب فراداده.
  • developerMetadata (شیء، الزامی): مقادیر فراداده به‌روزشده.
  • ‫fields (رشته، الزامی): پوشش فیلد.
  • ‫deleteDeveloperMetadata: فراداده توسعه‌دهنده را حذف می‌کند. طرح‌واره:
  • dataFilter (شیء، الزامی): فیلتری که معیارهای فراداده را برای حذف توصیف می‌کند.
  • ‫randomizeRange: ترتیب ردیف‌های محدوده را تصادفی می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده جدولی برای تصادفی‌سازی.
  • ‫addDimensionGroup: گروهی را در محدوده مشخص‌شده ایجاد می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده بُعد برای گروه‌بندی ({"sheetId": int, "dimension": "ROWS"|"COLUMNS", "startIndex": int, "endIndex": int}).
  • ‫deleteDimensionGroup: گروهی را در محدوده مشخص‌شده حذف می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده بُعد گروه برای حذف کردن.
  • ‫updateDimensionGroup: وضعیت گروه مشخص‌شده را به‌روز می‌کند. طرح‌واره:
  • ‫dimensionGroup (شیء، الزامی): تعریف گروه ({"range": DimensionRange, "depth": int, "collapsed": bool}).
  • ‫fields (رشته، الزامی): پوشش فیلد (برای نمونه "collapsed").
  • ‫trimWhitespace: سلول‌های فضای سفید (مثل فاصله‌ها، کلیدهای جهش، یا خطوط جدید) را پیرایش می‌کند. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده جدولی که سلول‌های آن باید پیرایش شود.
  • deleteDuplicates: ردیف‌های حاوی مقادیر تکراری را در ستون‌های مشخص‌شده محدوده سلول برمی‌دارد. طرح‌واره:
  • ‫range (شیء، الزامی): محدوده جدولی که موارد تکراری از آن برداشته شود.
  • comparisonColumns (آرایه DimensionRange، اختیاری): ستون‌های خاص برای تجزیه‌وتحلیل.
  • ‫updateEmbeddedObjectBorder: حاشیه یک شیء جاسازی‌شده را به‌روزرسانی می‌کند. طرح‌واره:
  • ‫objectId (عدد صحیح، الزامی): شناسه شیء جاسازی‌شده.
  • ‫border (شیء، الزامی): تعریف حاشیه ({"colorStyle": ColorStyle, "section": "ALL"}).
  • ‫fields (رشته، الزامی): پوشش فیلد.
  • ‫addSlicer: برش‌گر اضافه می‌کند. طرح‌واره:
  • ‫slicer (شیء، الزامی): تعریف جداکننده ({"spec": {"dataRange": GridRange, "columnIndex": int, "title": string}, "position": {"overlayPosition": {"anchorCell": {"sheetId": int, "rowIndex": int, "columnIndex": int}}}}).
  • ‫updateSlicerSpec: مشخصات برش‌گر را به‌روزرسانی می‌کند. طرح‌واره:
  • ‫slicerId (عدد صحیح، الزامی): شناسه برش‌دهنده.
  • ‫spec (شیء، الزامی): مشخصات جداکننده جدید.
  • ‫fields (رشته، الزامی): پوشش فیلد.
  • ‫addDataSource: منبع داده‌ای اضافه می‌کند. طرح‌واره:
  • ‫dataSource (شیء، الزامی): تعریف منبع داده ({"spec": {"bigQuery": {"projectId": string, "query": string}}}).
  • ‫updateDataSource: منبع داده‌ای را به‌روزرسانی می‌کند. طرح‌واره:
  • ‫dataSource (شیء، الزامی): تعریف منبع داده با dataSourceId.
  • ‫fields (رشته، الزامی): پوشش فیلد.
  • deleteDataSource: منبع داده‌ای را حذف می‌کند. طرح‌واره:
  • ‫dataSourceId (رشته، الزامی): شناسه منبع داده برای حذف.
  • ‫refreshDataSource: یک یا چند منبع داده و dbobject مرتبط را بازآوری می‌کند. طرح‌واره:
  • ‫dataSourceId (رشته، اختیاری) یا isAll (بولی، اختیاری) یا references (شیء، اختیاری).
  • ‫force (بولی، اختیاری): اینکه آیا بازآوری اجباری شود یا نه.
  • ‫cancelDataSourceRefresh: بازآوری‌های یک یا چند منبع داده و dbobjectهای مرتبط را لغو می‌کند. طرح‌واره:
  • ‫dataSourceId (رشته، اختیاری) یا isAll (بولی، اختیاری) یا references (شیء، اختیاری).
  • ‫addTable: جدولی اضافه می‌کند. طرح‌واره:
  • ‫table (شیء، الزامی): تعریف جدول ({"range": GridRange, "name": string, "hasHeaderRow": bool, "hasTotalsRow": bool}).
  • ‫updateTable: جدولی را به‌روزرسانی می‌کند. طرح‌واره:
  • ‫table (شیء، الزامی): تعریف جدول با tableId.
  • ‫fields (رشته، الزامی): پوشش فیلد.
  • ‫deleteTable: درخواست حذف جدول. طرح‌واره:
  • ‫tableId (رشته، الزامی): شناسه جدولی که باید حذف شود.
  • ‫insertComment: نظر را در صفحه‌گسترده درج می‌کند. طرح‌واره:
  • ‫content (رشته، الزامی): محتوای نظر نوشتار ساده.
  • ‫coordinate (شیء، الزامی): مختصات جدولی در برگ برای ثابت کردن نظر:
    • sheetId (عدد صحیح، الزامی): شناسه برگ.
    • ‫rowIndex (عدد صحیح، الزامی): شاخص سطر مبنا صفر.
    • ‫columnIndex (عدد صحیح، الزامی): شاخص ستون صفرمبنا.
  • ‫assigneeEmailAddress (رشته، اختیاری): نشانی ایمیل واگذارشده نظر.
  • addCommentReply: پاسخی به رشته نظر موجود اضافه می‌کند. همچنین برای حل‌وفصل یا باز کردن مجدد رشته استفاده می‌شود. طرح‌واره:
  • ‫commentId (رشته، الزامی): شناسه رشته نظر.
  • ‫post (شیء، الزامی):
    • content (رشته، الزامی است مگر اینکه commentAction روی RESOLVE یا REOPEN تنظیم شده باشد): محتوای نوشتاری ساده پست پاسخ.
    • ‫commentAction (رشته، اختیاری): کنش انجام‌شده با این پاسخ ("RESOLVE" یا "REOPEN").
    • ‫assigneeEmail (رشته، اختیاری): نشانی ایمیل برای اختصاص دادن رشته به آن.
  • updateCommentPost: محتوای پست نظر در رشته نظر را به‌روز می‌کند. طرح‌واره:
  • ‫commentId (رشته، الزامی): شناسه رشته نظر.
  • ‫postId (رشته، الزامی): شناسه پست نظر برای به‌روزرسانی.
  • ‫content (رشته، الزامی): محتوای به‌روزشده پست نظر.
  • ‫deleteComment: رشتهٔ نظرات را حذف می‌کند. طرح‌واره:
  • ‫commentId (رشته، الزامی): شناسه رشته نظر برای حذف.
  • ‫deleteCommentReply: پست پاسخ را حذف می‌کند. طرح‌واره:
  • ‫commentId (رشته، الزامی): شناسه رشته نظر.
  • ‫postId (رشته، الزامی): شناسه پست پاسخ برای حذف.

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

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

UpdateContentRequest

نمایش JSON 
{
  "spreadsheetId": string,
  "requests": [
    {
      object
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
فیلدها
spreadsheetId

string

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

object (Struct format)

الزامی. فهرستی از به‌روزرسانی‌ها برای اعمال در صفحه‌گسترده. هر درخواست باید یک شیء «درخواست» معتبر spreadsheets.batchUpdate باشد که از طرح مستندشده در https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request استفاده می‌کند. درخواست‌ها به ترتیبی که مشخص شده‌اند اعمال خواهند شد. اگر درخواستی معتبر نباشد، هیچ درخواستی اعمال نخواهد شد.
writeControl

object (WriteControl)

اختیاری. نحوه اجرای درخواست‌های نوشتن را کنترل می‌کند.

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)

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

WriteControl

نمایش JSON 
{

  "requiredRevisionId": string
}
فیلدها
فیلد اتحادیه control. نسخه صفحه‌گسترده‌ای را که باید در آن نوشت و نحوه عملکرد درخواست را درصورتی‌که آن نسخه نسخه فعلی صفحه‌گسترده نباشد تعیین می‌کند. ‫control فقط می‌تواند یکی از موارد زیر باشد:
requiredRevisionId

string

شناسه بازبینی صفحه‌گسترده‌ای که درخواست نوشتن روی آن اعمال خواهد شد. اگر این آخرین نسخه اصلاح‌شده سند نیست، درخواست پردازش نخواهد شد و خطای درخواست بد ۴۰۰ برمی‌گرداند.

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

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