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: تعدِّل خصائص جدول البيانات.
  • ‫updateSheetProperties: تعدّل خصائص ورقة جدول.
  • ‫updateDimensionProperties: تعديل خصائص السمات
  • updateNamedRange: تعدّل نطاقًا مُعنونًا.
  • repeatCell: تكرّر هذه الدالة خلية واحدة في نطاق.
  • addNamedRange: لإضافة نطاق مُعنوَن
  • deleteNamedRange: لحذف نطاق مُعنوَن
  • addSheet: لإضافة ورقة
  • deleteSheet: لحذف ورقة بيانات
  • autoFill: تملأ هذه السمة المزيد من البيانات تلقائيًا استنادًا إلى البيانات الحالية.
  • cutPaste: يقتطع البيانات من منطقة واحدة ويلصقها في منطقة أخرى.
  • copyPaste: لنسخ البيانات من منطقة ولصقها في منطقة أخرى
  • mergeCells: لدمج الخلايا معًا
  • ‫unmergeCells: لإلغاء دمج الخلايا المدمجة
  • ‫updateBorders: تعدّل حدود نطاق من الخلايا.
  • updateCells: تعدّل هذه الطريقة العديد من الخلايا في الوقت نفسه.
  • addFilterView: إضافة عرض فلتر
  • appendCells: لإلحاق الخلايا بعد آخر صف يتضمّن بيانات في ورقة.
  • clearBasicFilter: يمحو الفلتر الأساسي في ورقة.
  • deleteDimension: لحذف الصفوف أو الأعمدة في ورقة بيانات
  • deleteEmbeddedObject: لحذف عنصر مضمّن (مثل رسم بياني أو صورة) في ورقة
  • deleteFilterView: لحذف عرض فلتر من ورقة.
  • duplicateFilterView: لإنشاء نسخة طبق الأصل من طريقة عرض الفلتر
  • ‫duplicateSheet: لإنشاء نسخة طبق الأصل من ورقة
  • findReplace: تعثر هذه الدالة على بعض النصوص وتستبدلها بنصوص أخرى.
  • insertDimension: لإدراج صفوف أو أعمدة جديدة في ورقة
  • ‫insertRange: تُدرج هذه الطريقة خلايا جديدة في جدول بيانات، ما يؤدي إلى نقل الخلايا الحالية.
  • moveDimension: تنقل الصفوف أو الأعمدة إلى موقع آخر في ورقة.
  • updateEmbeddedObjectPosition: تعدّل موضع عنصر مضمّن (مثل رسم بياني أو صورة).
  • pasteData: تلصق هذه الدالة البيانات (بتنسيق HTML أو بتنسيق محدد) في ورقة.
  • textToColumns: تحوّل عمودًا من النص إلى عدة أعمدة من النص.
  • updateFilterView: تعدّل هذه الطريقة خصائص عرض الفلتر.
  • deleteRange: لحذف نطاق من الخلايا من ورقة، مع نقل الخلايا المتبقية
  • appendDimension: تُلحق السمات بنهاية ورقة البيانات.
  • addConditionalFormatRule: لإضافة قاعدة تنسيق شرطي جديدة
  • updateConditionalFormatRule: تعدّل قاعدة تنسيق شرطي حالية.
  • ‫deleteConditionalFormatRule: تحذف هذه السمة قاعدة تنسيق شرطي حالية.
  • sortRange: لترتيب البيانات في نطاق
  • setDataValidation: تضبط هذه السمة التحقّق من صحة البيانات لخلية واحدة أو أكثر.
  • ‫setBasicFilter: تضبط هذه السمة الفلتر الأساسي على ورقة.
  • addProtectedRange: إضافة نطاق محمي
  • ‫updateProtectedRange: تعدّل نطاقًا محميًا.
  • deleteProtectedRange: لحذف نطاق محمي
  • autoResizeDimensions: يتم تغيير حجم بُعد واحد أو أكثر تلقائيًا استنادًا إلى محتوى الخلايا في هذا البُعد.
  • addChart: إضافة رسم بياني
  • ‫updateChartSpec: تعديل مواصفات رسم بياني
  • ‫updateBanding: تعديل نطاق مقسَّم إلى شرائح
  • addBanding: إضافة نطاق جديد بنظام الأشرطة
  • deleteBanding: لإزالة نطاق مقسّم إلى فئات
  • createDeveloperMetadata: لإنشاء بيانات وصفية جديدة للمطوّر
  • ‫updateDeveloperMetadata: تعديل إدخال حالي للبيانات الوصفية للمطوّر
  • deleteDeveloperMetadata: لحذف البيانات الوصفية للمطوّر
  • randomizeRange: لترتيب الصفوف في نطاق بترتيب عشوائي
  • ‫addDimensionGroup: تنشئ مجموعة على النطاق المحدّد.
  • ‫deleteDimensionGroup: لحذف مجموعة ضمن النطاق المحدّد
  • updateDimensionGroup: تعدِّل حالة المجموعة المحدّدة.
  • trimWhitespace: تزيل المسافات البيضاء (مثل المسافات أو علامات التبويب أو الأسطر الجديدة) من الخلايا.
  • ‫deleteDuplicates: لإزالة الصفوف التي تحتوي على قيم مكرّرة في الأعمدة المحدّدة لنطاق الخلايا
  • updateEmbeddedObjectBorder: تعديل حدود عنصر مضمَّن
  • addSlicer: إضافة فلتر نطاق بيانات
  • ‫updateSlicerSpec: تعدّل مواصفات أداة التقطيع.
  • addDataSource: إضافة مصدر بيانات
  • ‫updateDataSource: تعدّل مصدر بيانات.
  • deleteDataSource: لحذف مصدر بيانات.
  • ‫refreshDataSource: يعيد تحميل مصدر بيانات واحد أو أكثر وكائنات قاعدة البيانات المرتبطة به.
  • ‫cancelDataSourceRefresh: تلغي عمليات إعادة تحميل مصدر بيانات واحد أو أكثر وكائنات قاعدة البيانات المرتبطة به.
  • addTable: لإضافة جدول
  • ‫updateTable: تعدّل جدولاً.
  • ‫deleteTable: طلب لحذف جدول

يوضّح المثال التالي كيفية استخدام curl لاستدعاء أداة update_spreadsheet MCP.

طلب Curl 
curl --location 'https://sheetsmcp.googleapis.com/mcp' \
--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 tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

UpdateContentRequest

تمثيل JSON 
{
  "spreadsheetId": string,
  "requests": [
    {
      object
    }
  ]
}
الحقول
spreadsheetId

string

الحقل مطلوب. معرّف جدول البيانات المطلوب تعديله
requests[]

object (Struct format)

الحقل مطلوب. قائمة بالتعديلات التي سيتم تطبيقها على جدول البيانات. يجب أن يكون كل طلب كائنًا صالحًا من نوع spreadsheets.batchUpdate Request، باستخدام المخطط الموضّح في: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request سيتم تطبيق الطلبات بالترتيب الذي تم تحديده. إذا كان أي طلب غير صالح، لن يتم تطبيق أي طلبات.

بنية

تمثيل 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 قيمة فارغة

مخطط الناتج

تمثّل هذه السمة عنصر JSON.

خريطة غير مرتبة للقيمة والمفتاح، تهدف إلى التقاط دلالات عنصر JSON بشكل مثالي. يتيح ذلك تحليل أي حمولة JSON عشوائية كحقل رسالة بتنسيق ProtoJSON.

يتّبع هذا النوع إرشادات RFC 8259 بشأن JSON القابل للتشغيل التفاعلي: لا يمكن لهذا النوع تمثيل قيم Int64 كبيرة أو أرقام NaN/Infinity، لأنّ تنسيق JSON لا يتيح بشكل عام هذه القيم في نوع الأرقام.

إذا كنت لا تنوي تحليل JSON عشوائي في رسالتك، يجب استخدام رسالة مكتوبة مخصّصة بدلاً من هذا النوع.

بنية

تمثيل 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 قيمة فارغة

التعليقات التوضيحية للأدوات

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