MCP Tools Reference: drivemcp.googleapis.com

الأداة: search_files

يمكنك استدعاء هذه الأداة للبحث عن ملفات Drive باستخدام طلب بحث منظَّم.

يتطلّب الحقل query استخدام عوامل تشغيل البحث عن طلبات البحث.

تحتوي سلسلة طلب البحث على الأجزاء الثلاثة التالية: query_term operator values حيث:

  • query_term هي عبارة البحث أو الحقل الذي سيتم البحث فيه.
  • تحدّد operator شرط عبارة البحث.
  • values هي القيم المحدّدة التي يجب استخدامها لفلترة نتائج البحث.

عبارات طلب البحث

يعرض الجدول التالي عبارات طلب البحث الصالحة مع أوصافها:

عبارة طلب البحث عوامل التشغيل الصالحة الاستخدام
title ‫contains، =، != تمثّل هذه السمة عنوان الملف. أحِطها بعلامات اقتباس مفردة ('). تخطَّ علامات الاقتباس المفردة في طلبات البحث باستخدام \'، مثل 'Valentine\'s Day'.
fullText contains تُستخدَم لتحديد ما إذا كان title أو النص في محتوى الملف متطابقًا. أحِطها بعلامات اقتباس مفردة ('). تخطَّ علامات الاقتباس المفردة في طلبات البحث باستخدام \'، مثل 'Valentine\'s Day'.
mimeType ‫contains، =، != نوع MIME للملف أحِطها بعلامات اقتباس مفردة ('). تخطَّ علامات الاقتباس المفردة في طلبات البحث باستخدام \'، مثل 'Valentine\'s Day'.
modifiedTime <=، و<، و=، و!=، و>، و>= تاريخ آخر تعديل للملف تنسيق RFC 3339، المنطقة الزمنية التلقائية هي التوقيت العالمي المتفق عليه، مثل 2012-06-04T12:00:00-08:00. لا يمكن مقارنة الحقول من النوع date.
viewedByMeTime <=، و<، و=، و!=، و>، و>= التاريخ الذي عرض فيه المستخدم ملفًا آخر مرة تنسيق RFC 3339، المنطقة الزمنية التلقائية هي التوقيت العالمي المتفق عليه، مثل 2012-06-04T12:00:00-08:00. لا يمكن مقارنة الحقول من النوع date.
parentId ‫=، != ما إذا كان العنصر الرئيسي يساوي رقم التعريف المحدّد. يمكن استخدام root لتحديد "ملفاتي" في حساب المستخدم التي تعمل كتسلسل هرمي أساسي.
owner ‫=، != المستخدم الذي يملك الملف يمكن استخدام me لتحديد المستخدم الذي يقدّم الطلب.
sharedWithMe ‫=، != الملفات الموجودة في مجموعة "تمت مشاركتها معي" الخاصة بالمستخدم يتم إدراج جميع مستخدمي الملف في قائمة التحكّم بالوصول (ACL) الخاصة بالملف. يمكن أن تكون القيمة true أو false.
createdTime <=، و<، و=، و!=، و>، و>= تاريخ إنشاء الملف استخدِم تنسيق RFC 3339، والمنطقة الزمنية التلقائية هي التوقيت العالمي المنسّق (UTC)، مثل 2012-06-04T12:00:00-08:00.

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

يعرض الجدول التالي عوامل تشغيل طلب البحث الصالحة:

عامل التشغيل الاستخدام
contains يتوفّر محتوى إحدى السلسلتين في السلسلة الأخرى.
= يكون محتوى السلسلة أو القيمة المنطقية مساويًا للمحتوى الآخر.
!= لا يتطابق محتوى السلسلة أو القيمة المنطقية مع المحتوى الآخر.
< قيمة أقل من قيمة أخرى
<= قيمة أصغر من أو تساوي قيمة أخرى
> قيمة أكبر من قيمة أخرى
>= قيمة أكبر من أو تساوي قيمة أخرى
in يتم تضمين عنصر في مجموعة.
and عرض العناصر التي تطابق كلا طلبَي البحث
or عرض العناصر التي تطابق أيًا من طلبَي البحث
not تعمل هذه السمة على نفي طلب بحث.
has تحتوي المجموعة على عنصر يطابق المَعلمات.

تشمل بعض الأمثلة على طلبات البحث ما يلي:

  • 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' \
--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 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
}
الحقول
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

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

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

تمثيل 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: ❌