MCP Tools Reference: sheetsmcp.googleapis.com

الأداة: get_spreadsheet

تعرض هذه الدالة محتوى جدول البيانات المحدّد. تعرض هذه الطريقة العناوين وأسماء أوراق البيانات وخصائص الشبكة والبيانات الوصفية الأخرى لرقم تعريف جدول البيانات المحدّد. وتعرض أيضًا بيانات الشبكة الكاملة إذا طُلب ذلك.

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

المخطط: - spreadsheet_id (سلسلة، مطلوب): رقم تعريف جدول البيانات المطلوب. ‫- include_grid_data (قيمة منطقية، اختيارية): تكون القيمة True إذا كان يجب عرض بيانات الشبكة. الخيار التلقائي هو "خطأ". ‫- fields (مصفوفة من السلاسل، اختيارية): أقنعة الحقول التي تحدّد السمات المطلوب عرضها (مثلاً ["sheets.properties.sheetId", "sheets.properties.title"]). - comments_included (قيمة منطقية، اختيارية): إذا كانت القيمة صحيحة، سيتم تضمين التعليقات في الردّ. الخيار التلقائي هو "خطأ". ‫- ranges (صفيف من السلاسل، اختياري): نطاقات A1 أو R1C1 المطلوب استردادها من جدول البيانات. في حال عدم تحديدها، يتم عرض جدول البيانات بأكمله.

يوضّح نموذج الرمز البرمجي التالي كيفية استخدام curl لاستدعاء أداة MCP‏ get_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": "get_spreadsheet",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

GetContentRequest

تمثيل JSON 
{
  "spreadsheetId": string,
  "includeGridData": boolean,
  "fields": [
    string
  ],
  "ranges": [
    string
  ],

  "commentsIncluded": boolean
}
الحقول
spreadsheetId

string

الحقل مطلوب. رقم تعريف جدول البيانات المطلوب
includeGridData

boolean

تكون القيمة "صحيح" إذا كان يجب عرض بيانات الشبكة.
fields[]

string

اختيارية: قناع حقل لتحديد السمات التي يجب عرضها من Spreadsheets API. يُرجى الاطّلاع على https://developers.google.com/workspace/sheets/api/guides/field-masks لمزيد من المعلومات حول كيفية استخدام أقنعة الحقول. ملاحظة مهمة: استخدِم المسارات الهرمية استنادًا إلى بنية JSON للاستجابة في Sheets API. - على سبيل المثال، للحصول على عنوان ورقة البيانات ورقم تعريفها، استخدِم "sheets.properties.sheetId" و"sheets.properties.title" بدلاً من "title,sheetId". - تضمين الحقول التي تحتاجها فقط. - للحصول على الجداول، استخدِم: "sheets.tables" أو "sheets.properties". - للحصول على عناوين أوراق البيانات وأرقام تعريفها، استخدِم: "sheets.properties.sheetId" و"sheets.properties.title".
ranges[]

string

اختيارية: ترميز A1 أو ترميز R1C1 للنطاقات المطلوب استردادها من جدول البيانات. في حال عدم تحديدها، يتم عرض جدول البيانات بأكمله.

حقل الربط _comments_included

يمكن أن يكون التعليق _comments_included إحدى القيم التالية فقط:
commentsIncluded

boolean

اختيارية: إذا كانت القيمة "صحيح"، سيتم تضمين التعليقات في الردّ. لا يتم تضمين التعليقات تلقائيًا.

مخطط النتائج

GetContentResponse

تمثيل JSON 
{
  "content": {
    object
  }
}
الحقول
content

object (Struct format)

جدول البيانات، بتنسيق JSON لمرجع Sheets API Spreadsheet.

بنية

تمثيل 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: إذا كانت القيمة "صحيح"، يمكن للأداة التفاعل مع "عالم مفتوح" من الكيانات الخارجية. إذا كانت القيمة "خطأ"، يمكن للأداة التفاعل مع الكيانات الداخلية فقط. على سبيل المثال، ستكون أداة بحث الويب عالمًا مفتوحًا، في حين أنّ أداة الذاكرة لن تكون عالمًا مفتوحًا.

تلميح حول الإجراءات المدمّرة: ❌ | تلميح حول الإجراءات المتكررة: ✅ | تلميح حول الإذن بالقراءة فقط: ✅ | تلميح حول العالم المفتوح: ✅

نطاقات التفويض

يتطلب أحد نطاقات OAuth التالية:

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