تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
لعرض الحقول التي تحتاج إليها بالضبط وتحسين الأداء، استخدِم المَعلمة fieldssystem في طلب الطريقة.
يوضّح هذا المستند كيفية استخدام المَعلمة fields في Google Drive.
طريقة عمل المَعلمة fields
تستخدِم المَعلمة fieldsFieldMask لفلترة الردود. تُستخدَم أقنعة الحقول لتحديد مجموعة فرعية من الحقول التي يجب أن يعرضها الطلب. يُعدّ استخدام قناع الحقل من ممارسات التصميم الجيدة للتأكّد من أنّك لا تطلب بيانات غير ضرورية، ما يساعد بدوره في تجنُّب وقت المعالجة غير الضروري.
في حال عدم تحديد المَعلمة fields، يعرض الخادم مجموعة تلقائية من الحقول الخاصة بالطريقة. على سبيل المثال، لا تعرض الطريقة list في الطريقة files سوى الحقول kind وid وname وmimeType. تعرض الطريقة get في المورد permissions مجموعة مختلفة من الحقول التلقائية.
بالنسبة إلى جميع طرق الموارد about وcomments (باستثناء delete) وreplies (باستثناء delete)، عليك ضبط المَعلمة fields. لا تعرض هذه الطرق مجموعة تلقائية من الحقول.
بعد أن يعالج الخادم طلبًا صالحًا يتضمّن المَعلمة fields، سيعرض رمز الحالة HTTP 200 OK، بالإضافة إلى البيانات المطلوبة. إذا كانت المَعلمة fields تتضمّن خطأ أو كانت غير صالحة لأي سبب آخر، سيعرض الخادم رمز الحالة 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/*' جميع حقول تفاصيل الأذونات المتاحة لكل إذن. يُرجى العِلم أنّ استخدام حرف البدل يمكن أن يؤدي إلى تأثيرات سلبية في أداء الطلب.
الطلب
في هذا المثال، نقدّم مَعلمة مسار رقم تعريف الملف وعدّة حقول كمَعلمة طلب بحث في الطلب. تعرض الاستجابة قيم الحقول لمعرّف الملف.
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).
الطلب
في هذا المثال، نقدّم مَعلمة مسار رقم تعريف الملف وعدّة حقول، بما في ذلك حقول معيّنة لمورد الأذونات المتداخلة، كمَعلمة طلب بحث في الطلب. تعرض الاستجابة قيم الحقول لمعرّف الملف.
تاريخ التعديل الأخير: 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,["To 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\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\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\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- [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)"]]
