عرض حقول معيّنة لملف

لعرض الحقول الدقيقة التي تحتاجها وتحسين الأداء، استخدِم مَعلمة طلب البحث fields في استدعاء الطريقة.

بشكل افتراضي، يرسل الخادم مجموعة من الحقول الخاصة بالمورد الذي يتم الاستعلام عنه. على سبيل المثال، قد تعرض الطريقة files.get السمة id وname وmimeType فقط للمورد files. تعرض الطريقة permissions.get مجموعة مختلفة من الحقول التلقائية لمورد permissions.

بعد أن يعالج الخادم طلبًا صالحًا يتضمّن مَعلمة طلب البحث fields، يرسل رمز الحالة HTTP 200 OK مع البيانات المطلوبة مرة أخرى. وإذا كانت مَعلمة طلب البحث للحقول تتضمّن خطأ أو غير صالحة، يعرض الخادم رمز الحالة HTTP 400 Bad Request، إلى جانب رسالة خطأ توضّح المشكلة في اختيار الحقول. على سبيل المثال، يؤدي استخدام files.list(fields='files(id,capabilities,canAddChildren)') إلى ظهور الخطأ " 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

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

استرجاع حقول مورد مدمج

عندما يشير حقل إلى مورد آخر، يمكنك تحديد حقول المورد المُدمج التي يجب جلبها.

على سبيل المثال، لاسترداد الحقل role (المورد المتداخل) لمورد permissions، استخدِم أيًّا من الخيارات التالية:

• permissions.get مع fields=role أو fields=*
• files.get مع fields=permissions(role) أو fields=permissions/role
• files.get مع fields=permissions للإشارة إلى جميع حقول المورد المُدمج.
• changes.list مع fields=changes(file(permissions(role))).

لاسترداد حقول متعددة، استخدِم قائمة مفصولة بفواصل. على سبيل المثال، files.list مع fields=files(id,name,createdTime,modifiedTime,size).

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}