MCP Tools Reference: drivemcp.googleapis.com

الأداة: search_files

ابحث عن ملفات Drive باستخدام طلب بحث منظَّم (البنية: query_term operator values). ادمج العبارات مع and وor وnot والأقواس. يجب أن تكون قيم السلسلة النصية بين علامتَي اقتباس مفردتَين، ويجب إلغاء الأحرف الخاصة بعلامات الاقتباس المضمّنة باستخدام \'.

عبارات طلب البحث وعوامل التشغيل:

  • ‫title (ops: contains, =, !=) — عنوان الملف
  • ‫fullText (ops: contains) — العنوان أو نص الصفحة
  • ‫mimeType (ops: contains, =, !=) — نوع MIME
  • ‫modifiedTime أو viewedByMeTime أو createdTime (العمليات: <= و< و= و!= و> و>=). استخدِم التوقيت العالمي المتفق عليه وفقًا لمعيار RFC 3339، مثل 2012-06-04T12:00:00-08:00. أنواع التواريخ غير قابلة للمقارنة.
  • parentId (ops: =، !=). استخدِم 'root' لـ "ملفاتي" الخاصة بالمستخدم.
  • owner (فريق العمليات: =، !=). استخدِم 'me' للمستخدم الذي يقدّم الطلب.
  • ‫sharedWithMe (العمليات: =، !=). القيم: true أو false.

عوامل تشغيل أخرى: and وor وnot

أمثلة:

  • title contains 'hello' and title contains 'goodbye'
  • modifiedTime > '2024-01-01T00:00:00Z' and (mimeType contains 'image/' or mimeType contains 'video/')
  • parentId = '1234567'
  • fullText contains 'hello'
  • owner = 'test@example.org'
  • sharedWithMe = true
  • ‫owner = 'me' (للملفات التي يملكها المستخدم)

استخدِم next_page_token لتقسيم المحتوى إلى صفحات. يعني الردّ الفارغ أنّه لم تعُد هناك نتائج أخرى.

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

طلب Curl 
curl --location 'https://drivemcp.googleapis.com/mcp/v1' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_files",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

طلب البحث في الملفات

SearchFilesRequest

تمثيل JSON 
{
  "query": string,

  "pageToken": string

  "pageSize": integer

  "excludeContentSnippets": boolean
}
الحقول
query

string

طلب البحث

حقل الربط _page_token

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

string

تمثّل هذه المَعلمة الرمز المميّز للصفحة المطلوب استخدامه لتقسيم النتائج إلى صفحات.

حقل الربط _page_size

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

integer

الحد الأقصى لعدد الملفات التي سيتم عرضها في كل صفحة

حقل الربط _exclude_content_snippets

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

boolean

في حال ضبط القيمة على "true"، سيتم استبعاد مقتطف المحتوى من الردّ.

مخطط النتائج

الردّ على طلب البحث عن الملفات

SearchFilesResponse

تمثيل JSON 
{
  "files": [
    {
      object (File)
    }
  ],

  "nextPageToken": string
}
الحقول
files[]

object (File)

النتائج فقط. قائمة الملفات

حقل الربط _next_page_token

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

string

الرمز المميز للصفحة التالية.

ملف

تمثيل JSON 
{
  "id": string,
  "title": string,
  "parentId": string,

  "mimeType": string

  "fileSize": string

  "description": string

  "fileExtension": string

  "contentSnippet": string

  "viewUrl": string

  "sharedWithMeTime": string

  "createdTime": string

  "modifiedTime": string

  "viewedByMeTime": string

  "owner": string

  "canAddChildren": boolean
}
الحقول
id

string

رقم تعريف الملف الذي تم استرجاعه.
title

string

تمثّل هذه السمة عنوان الملف.
parentId

string

المعرّف (اختياري) للعنصر الرئيسي للملف

حقل الربط _mime_type

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

string

نوع MIME للملف.

حقل الربط _file_size

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

string (int64 format)

حجم الملف بالبايت

حقل الربط _description

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

string

تمثّل هذه السمة وصف الملف.

حقل الربط _file_extension

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

string

تمثّل هذه السمة امتداد الملف الأصلي، ولا يتم ملؤها إلا للملفات التي يتم تخزين محتواها في Drive.

حقل الربط _content_snippet

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

string

مقتطف تم إنشاؤه حول محتوى الملف

حقل الربط _view_url

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

string

تمثّل هذه السمة عنوان URL لعرض الملف.

حقل الربط _shared_with_me_time

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

string (Timestamp format)

الوقت الذي تمت فيه مشاركة الملف مع مقدّم الطلب

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

حقل الربط _created_time

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

string (Timestamp format)

الوقت الذي تم فيه إنشاء الملف

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

حقل الربط _modified_time

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

string (Timestamp format)

يشير هذا الحقل إلى تاريخ آخر مرة تم فيها تعديل الملف.

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

حقل الربط _viewed_by_me_time

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

string (Timestamp format)

آخر مرة اطّلع فيها مقدّم الطلب على الملف

يستخدم المعيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه مُمثلاً بالتوقيت العالمي المنسَّق مع حرف Z في النهاية ويستخدم الأرقام الجزئية 0 أو 3 أو 6 أو 9. تُقبل أيضًا المعادلات الأخرى التي لا تستخدم حرف Z. أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30".

حقل الربط _owner

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

string

عنوان البريد الإلكتروني لمالك الملف

حقل الربط _can_add_children

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

boolean

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

الطابع الزمني

تمثيل JSON 
{
  "seconds": string,
  "nanos": integer
}
الحقول
seconds

string (int64 format)

تمثّل هذه السمة عدد ثواني التوقيت العالمي المنسق (UTC) المنقضية منذ بداية حقبة يونكس 1970-01-01T00:00:00Z. يجب أن تتراوح القيمة بين ‎-62135596800 و253402300799، بما في ذلك طرفي النطاق (وهو ما يتوافق مع النطاق من 0001-01-01T00:00:00Z إلى 9999-12-31T23:59:59Z).
nanos

integer

تشير هذه السمة إلى أجزاء الثانية غير السالبة بدقة النانو ثانية هذا الحقل هو جزء من المدة بوحدة النانو ثانية، وليس بديلاً عن الثواني. يجب أن تتضمّن قيم الثواني السالبة مع الكسور قيمًا غير سالبة للنانو ثانية يتم احتسابها للأمام في الوقت. يجب أن تتراوح القيمة بين 0 و999,999,999، بما في ذلك طرفي النطاق.

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

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