با مجموعهها، منظم بمانید ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
برای برگرداندن فیلدهای دقیق مورد نیاز و بهبود عملکرد، از پارامتر سیستمfields در فراخوانی متد خود استفاده کنید.
این سند نحوه استفاده از پارامتر fields در Google Drive را توضیح می دهد.
نحوه عملکرد پارامتر فیلدها
پارامتر fields از یک FieldMask برای فیلتر کردن پاسخ استفاده می کند. ماسک فیلد برای تعیین زیرمجموعه ای از فیلدهایی که یک درخواست باید برگرداند استفاده می شود. استفاده از یک فیلد ماسک تمرین طراحی خوبی است تا اطمینان حاصل شود که داده‌های غیرضروری درخواست نمی‌کنید، که به نوبه خود به جلوگیری از زمان پردازش غیر ضروری کمک می‌کند.
اگر پارامتر fields را مشخص نکنید، سرور یک مجموعه پیش‌فرض از فیلدهای مخصوص روش را برمی‌گرداند. برای مثال، روش list در روش files فقط فیلدهای kind ، id ، name و mimeType را برمی‌گرداند. متد get در منبع permissions مجموعه متفاوتی از فیلدهای پیش فرض را برمی گرداند.
برای همه روش‌های منابع about ، comments (به استثنای delete )، و replies (به استثنای delete ) باید پارامتر fields تنظیم کنید. این روش ها مجموعه ای از فیلدهای پیش فرض را بر نمی گرداند.
پس از اینکه سرور یک درخواست معتبر را که شامل پارامتر fields است پردازش کرد، یک کد وضعیت HTTP 200 OK را به همراه داده های درخواستی برمی گرداند. اگر پارامتر فیلدها دارای خطا باشد یا در غیر این صورت نامعتبر باشد، سرور یک کد وضعیت HTTP 400 Bad Request را به همراه یک پیام خطایی مبنی بر مشکل انتخاب فیلدهای شما برمی گرداند. برای مثال، files.list(fields='files(id,capabilities,canAddChildren)') خطای "انتخاب فیلد نامعتبر canAddChildren" را نشان می دهد. پارامتر فیلدهای صحیح برای این مثال files.list(fields='files(id,capabilities/canAddChildren)') است.
برای تعیین فیلدهایی که می توانید با استفاده از پارامتر fields برگردانید، از صفحه مستندات منبعی که در حال جستجو هستید بازدید کنید. به عنوان مثال، برای اینکه ببینید چه فیلدهایی را می توانید برای یک فایل برگردانید، به مستندات منبع files مراجعه کنید. برای عبارات پرس و جوی خاص فایل، اصطلاحات و عملگرهای درخواست جستجو را ببینید.
قوانین فرمت پارامتر فیلد
فرمت مقدار پارامتر درخواست فیلدها بر اساس نحو XPath است. در زیر قوانین قالب بندی پارامتر fields آمده است. همه این قوانین از مثال های مربوط به متد files.get استفاده می کنند.
از یک لیست جدا شده با کاما برای انتخاب چندین فیلد مانند 'name, mimeType' استفاده کنید.
a/b برای انتخاب فیلد b که در فیلد a تودرتو است، مانند 'capabilities/canDownload' استفاده کنید. برای اطلاعات بیشتر، واکشی فیلدهای یک منبع تودرتو را ببینید.
از یک انتخابگر فرعی برای درخواست مجموعه ای از فیلدهای فرعی خاص از آرایه ها یا اشیاء با قرار دادن عبارات در پرانتز "()" استفاده کنید. برای مثال، 'permissions(id)' فقط شناسه مجوز را برای هر عنصر در آرایه مجوزها برمی‌گرداند.
برای برگرداندن تمام فیلدهای یک شی، از یک ستاره ( * ) به عنوان علامت عام در انتخاب فیلدها استفاده کنید. به عنوان مثال، 'permissions/permissionDetails/*' تمام فیلدهای جزئیات مجوز موجود را برای مجوز انتخاب می کند. توجه داشته باشید که استفاده از wildcard می تواند منجر به اثرات منفی عملکرد بر روی درخواست شود.
درخواست کنید
در این مثال، پارامتر مسیر ID فایل و چندین فیلد را به عنوان پارامتر پرس و جو در درخواست ارائه می کنیم. پاسخ مقادیر فیلد را برای شناسه فایل برمی گرداند.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared
وقتی یک فیلد به منبع دیگری ارجاع می‌دهد، می‌توانید مشخص کنید که کدام فیلد از منبع تودرتو باید واکشی شود.
به عنوان مثال، برای بازیابی فیلد role (منبع تودرتو) منبع permissions ، از یکی از گزینه های زیر استفاده کنید:
permissions.get با fields=role .
permissions.get با fields=* برای نمایش تمام فیلدهای permissions .
files.get با fields=permissions(role) یا fields=permissions/role .
files.get با fields=permissions برای نمایش تمام فیلدهای permissions .
changes.list با fields=changes(file(permissions(role))) .
برای بازیابی چندین فیلد، از یک لیست جدا شده با کاما استفاده کنید. به عنوان مثال، files.list با fields=files(id,name,createdTime,modifiedTime,size) .
درخواست کنید
در این مثال، پارامتر مسیر ID فایل و چندین فیلد، از جمله فیلدهای خاصی از منبع مجوزهای تودرتو، را به عنوان پارامتر پرس و جو در درخواست ارائه می‌کنیم. پاسخ مقادیر فیلد را برای شناسه فایل برمی گرداند.
تاریخ آخرین بهروزرسانی 2025-08-04 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-04 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Return specific fields\n\nTo return the exact fields you need, and to improve performance, use the\n`fields` [system\nparameter](https://cloud.google.com/apis/docs/system-parameters#definitions) in\nyour method call.\n\nThis document explains how to use the `fields` parameter in Google Drive.\n\nHow the fields parameter works\n------------------------------\n\nThe `fields` parameter uses a\n[FieldMask](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask)\nfor response filtering. Field masks are used to specify a subset of fields that\na request should return. Using a field mask is good design practice to make sure\nthat you don't request unnecessary data, which in turn helps avoid unnecessary\nprocessing time.\n\nIf you don't specify the `fields` parameter, the server returns a default set of\nfields specific to the method. For example, the\n[`list`](/workspace/drive/api/reference/rest/v3/files/list) method on the [`files`](/workspace/drive/api/reference/rest/v3/files) method only returns the `kind`, `id`, `name`, and\n`mimeType` fields. The [`get`](/workspace/drive/api/reference/rest/v3/permissions/get) method on the\n[`permissions`](/workspace/drive/api/reference/rest/v3/permissions) resource returns a different set\nof default fields.\n\nFor all methods of the [`about`](/workspace/drive/api/reference/rest/v3/about), [`comments`](/workspace/drive/api/reference/rest/v3/comments) (excluding `delete`), and [`replies`](/workspace/drive/api/reference/rest/v3/replies) (excluding `delete`) resources you *must* set the\n`fields` parameter. These methods don't return a default set of fields.\n\nAfter a server processes a valid request that includes the `fields` parameter,\nit returns an `HTTP 200 OK` status code, along with the requested data. If the\nfields parameter has an error or is otherwise invalid, the server returns an\n`HTTP 400 Bad Request` status code, along with an error message stating what's\nwrong with your fields selection. For example,\n`files.list(fields='files(id,capabilities,canAddChildren)')` yields an error of\n\"Invalid field selection canAddChildren.\" The correct fields parameter for this\nexample is `files.list(fields='files(id,capabilities/canAddChildren)')`.\n\nTo determine the fields you can return using the `fields` parameter, visit the\ndocumentation page of the resource you're querying. For example, to see what\nfields you can return for a file, refer to the `files` resource documentation.\nFor more file-specific query terms, see [Search query terms and operators](/workspace/drive/api/guides/ref-search-terms).\n| **Important:** Use query parameters that support data pagination (such as `maxResults` and `nextPageToken`) to reduce the results of each query to a manageable size. Otherwise, the performance gains possible with a [partial\n| response](/workspace/drive/api/guides/performance#partial) might not be realized.\n\nField parameter format rules\n----------------------------\n\nThe format of the fields request parameter value is loosely based on XPath\nsyntax. The following are formatting rules for the `fields` parameter. All these\nrules use examples related to the `files.get` method.\n\n- Use a comma-separated list to select multiple fields, such as `'name,\n mimeType'`.\n\n- Use `a/b` to select field `b` that's nested within field `a`, such as\n `'capabilities/canDownload'`. For more information, see [Fetch the fields of\n a nested resource](#nested).\n\n- Use a sub-selector to request a set of specific sub-fields of arrays or\n objects by placing expressions in parentheses \"()\". For example,\n `'permissions(id)'` returns only the permission ID for each element in the\n permissions array.\n\n- To return all fields in an object, use an asterisk (`*`) as a wildcard in\n field selections. For example, `'permissions/permissionDetails/*'` selects\n all available permission details fields per permission. Note that using the\n wildcard can lead to negative performance impacts on the request.\n\n**Request**\n\nIn this example, we provide the file ID path parameter and multiple fields as a query parameter in the request. The response returns the field values for the file ID. \n\n```scdoc\nGET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared\n```\n\n**Response** \n\n```text\n{\n \"name\": \"File1\",\n \"starred\": false,\n \"shared\": true\n }\n}\n```\n\nFetch the fields of a nested resource\n-------------------------------------\n\nWhen a field refers to another resource, you can specify which fields of the\nnested resource should be fetched.\n\nFor example, to retrieve the `role` field (nested resource) of the `permissions`\nresource, use any of the following options:\n\n- `permissions.get` with `fields=role`.\n- `permissions.get` with `fields=*` to show all `permissions` fields.\n- `files.get` with `fields=permissions(role)` or `fields=permissions/role`.\n- `files.get` with `fields=permissions` to show all `permissions` fields.\n- `changes.list` with `fields=changes(file(permissions(role)))`.\n\nTo retrieve multiple fields, use a comma-separated list. For example,\n`files.list` with `fields=files(id,name,createdTime,modifiedTime,size)`. \n**Request**\n\nIn this example, we provide the file ID path parameter and multiple fields, including certain fields of the nested permissions resource, as a query parameter in the request. The response returns the field values for the file ID. \n\n```carbon\nGET https://www.googleapis.com/drive/v3/files/\u003cvar translate=\"no\"\u003eFILE_ID\u003c/var\u003e?fields=name,starred,shared,permissions(kind,type,role)\n```\n\n**Response** \n\n```carbon\n{\n \"name\": \"File1\",\n \"starred\": false,\n \"shared\": true,\n \"permissions\": [\n {\n \"kind\": \"drive#permission\",\n \"type\": \"user\",\n \"role\": \"owner\"\n }\n ]\n}\n```\n\nRelated topics\n--------------\n\n- [Resolve errors](/workspace/drive/api/guides/handle-errors)\n- [Troubleshoot authentication and authorization issues](/workspace/drive/api/troubleshoot-authentication-authorization)\n- [Improve performance](/workspace/drive/api/guides/performance)"]]
