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: لإعادة تحميل مصدر بيانات واحد أو أكثر وعناصر dbobjects المرتبطة بها. المخطط:
  • ‫dataSourceId (سلسلة، اختيارية) أو isAll (قيمة منطقية، اختيارية) أو references (عنصر، اختياري).
  • ‫force (قيمة منطقية، اختيارية): لتحديد ما إذا كان يجب فرض إعادة التحميل
  • ‫cancelDataSourceRefresh: لإلغاء عمليات إعادة تحميل مصدر بيانات واحد أو أكثر وعناصر dbobjects المرتبطة بها المخطط:
  • ‫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 (عدد صحيح، مطلوب): فهرس الأعمدة ابتداءً من 0
  • ‫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

يمثّل هذا الحقل 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

رقم تعريف النسخة لجدول البيانات الذي سيتم تطبيق طلب الكتابة عليه إذا لم تكن هذه هي النسخة الأحدث من المستند، لن تتم معالجة الطلب وستظهر رسالة الخطأ ‎400 Bad Request.

عند عرض رقم تعريف نسخة مطلوبة في ردّ، يشير ذلك إلى رقم تعريف نسخة جدول البيانات بعد تطبيق الطلب.

NullValue

يمثّل هذا الحقل null بتنسيق JSON.

‫NullValue هو حارس يستخدم تعدادًا بقيمة واحدة فقط لتمثيل القيمة الفارغة لاتحاد النوع Value.

يُعتبر الحقل من النوع NullValue الذي يحتوي على أي قيمة غير 0 غير صالح. ستُصدر معظم أدوات تسلسل ProtoJSON قيمة Value مع ضبط null_value على أنّه null في JSON بغض النظر عن قيمة العدد الصحيح، وبالتالي ستتحوّل إلى قيمة 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

يمثّل هذا الحقل 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: إذا كانت القيمة صحيحة، لا تعدّل الأداة بيئتها. القيمة التلقائية: 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