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 (شیء، الزامی): محدوده جدولی برای حذف.
  • ‫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 برای فراخوانی ابزار MCP update_spreadsheet را نشان می‌دهد.

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

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

ساختار

نمایش 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

نشان‌دهنده JSON null است.
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

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

NullValue یک نگهبان است که از یک enum با تنها یک مقدار برای نمایش مقدار null برای اتحاد نوع Value استفاده می‌کند.

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

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

طرح خروجی

UpdateContentResponse

نمایش JSON 
{
  "content": {
    object
  }
}
فیلدها
content

object (Struct format)

پاسخ spreadsheets.batchUpdate، در قالب JSON از Sheets API، به‌علاوه فیلد status.

ساختار

نمایش 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

نشان‌دهنده JSON null است.
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

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

NullValue یک نگهبان است که از یک enum با تنها یک مقدار برای نمایش مقدار null برای اتحاد نوع Value استفاده می‌کند.

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

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

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

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

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

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

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ❌ | Open World Hint: ✅

دامنه‌های مجوز

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

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