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، منطقه زمانی پیش‌فرض UTC است، مانند 2012-06-04T12:00:00-08:00 . فیلدهای از نوع date قابل مقایسه نیستند.
viewedByMeTime <= ، < ، = ، != ، > ، >= تاریخی که کاربر آخرین بار فایلی را مشاهده کرده است. قالب RFC 3339، منطقه زمانی پیش‌فرض UTC است، مانند 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 --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
}'

طرحواره ورودی

درخواست جستجوی فایل‌ها

درخواست جستجو

نمایش 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

اگر مقدار آن درست باشد، قطعه محتوا از پاسخ حذف خواهد شد.

طرحواره خروجی

پاسخ به فایل‌های جستجو.

جستجوی فایل‌هاپاسخ

نمایش 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

آدرس اینترنتی برای مشاهده فایل.

فیلد اتحادیه _shared_with_me_time .

_shared_with_me_time فقط می‌تواند یکی از موارد زیر باشد:

sharedWithMeTime

string ( Timestamp format)

مدت زمانی که فایل با درخواست‌کننده به اشتراک گذاشته شده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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 را از زمان یونیکس ۱۹۷۰-۰۱-۰۱T۰۰:۰۰:۰۰Z نشان می‌دهد. باید بین -۶۲۱۳۵۵۹۶۸۰۰ و ۲۵۳۴۰۲۳۰۰۷۹۹ باشد (که معادل ۰۰۰۱-۰۱-۰۱T۰۰:۰۰:۰۰Z تا ۹۹۹۹-۱۲-۳۱T۲۳:۵۹:۵۹Z است).

nanos

integer

کسرهای غیرمنفی ثانیه با وضوح نانوثانیه. این فیلد بخش نانوثانیه از مدت زمان است، نه جایگزینی برای ثانیه. مقادیر منفی ثانیه با کسرها باید همچنان دارای مقادیر نانوثانیه غیرمنفی باشند که در زمان به جلو شمارش می‌شوند. باید بین ۰ تا ۹۹۹۹۹۹۹۹۹۹ باشد.

حاشیه‌نویسی ابزار

راهنمایی مخرب: ❌ | راهنمایی بی‌اثر: ✅ | راهنمایی فقط خواندنی: ✅ | راهنمایی جهان باز: ❌