MCP Tools Reference: sheetsmcp.googleapis.com

الأداة: insert_dimension

لإدراج صفوف أو أعمدة في ورقة بيانات في فهرس معيّن

يتوافق مع InsertDimensionRequest في واجهة برمجة التطبيقات REST API‏ spreadsheets.batchUpdate: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request

المخطط: - spreadsheet_id (سلسلة، مطلوب): معرّف جدول البيانات المطلوب تعديله. ‫- sheet_id (عدد صحيح، مطلوب): معرّف ورقة البيانات المطلوب إدراجها. ‫- dimension (سلسلة، مطلوبة): "ROWS" أو "COLUMNS". ‫- start_index (عدد صحيح، مطلوب): فهرس البداية المستند إلى 0 للإدراج (شامل). ‫- end_index (عدد صحيح، مطلوب): فهرس النهاية الذي يبدأ من 0 للإدراج (حصري). ‫- inherit_from_before (قيمة منطقية، اختيارية): تشير إلى ما إذا كان يجب تمديد خصائص السمات من السمات السابقة (true) أو اللاحقة (false).

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام curl لاستدعاء أداة MCP‏ insert_dimension.

طلب 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

الحقل مطلوب. فهرس البدء الذي يبدأ من 0 للإدراج (شامل).
endIndex

integer

الحقل مطلوب. فهرس النهاية الذي يبدأ من 0 للإدراج (حصري)
inheritFromBefore

boolean

ما إذا كان يجب تمديد خصائص الأبعاد من الأبعاد قبل الأبعاد المدرَجة حديثًا أو بعدها. القيمة True للوراثة من الأبعاد السابقة (وفي هذه الحالة يجب أن يكون فهرس البداية أكبر من 0)، والقيمة False للوراثة من الأبعاد اللاحقة.

السمة

يشير إلى السمة التي يجب تطبيق العملية عليها.

عمليات التعداد
DIMENSION_UNSPECIFIED هذه هي القيمة التلقائية، لذا لا تستخدِمها.
COLUMNS تعمل على أعمدة ورقة البيانات.
ROWS تعمل على صفوف ورقة بيانات.

مخطط النتائج

InsertDimensionResponse

تمثيل 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/spreadsheets