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

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

تستخدِم المَعلمة fields FieldMask لفلترة الاستجابة. تُستخدَم أقنعة الحقول لتحديد مجموعة فرعية من الحقول التي يجب أن يعرضها الطلب. يُعدّ استخدام قناع حقل من أفضل ممارسات التصميم للتأكّد من عدم طلب بيانات غير ضرورية، ما يساعد بدوره في تجنُّب وقت المعالجة غير الضروري.

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

بعد أن يعالج الخادم طلبًا صالحًا يتضمّن المَعلمة 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

الاستجابة

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

جلب حقول مورد مُدمَج

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

على سبيل المثال، لاسترداد حقل 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).

عرض مثال

الطلب

في هذا المثال، نوفّر مَعلمة مسار رقم تعريف الملف وحقولًا متعدّدة، بما في ذلك حقول معيّنة لمصدر الأذونات المتداخلة، كمَعلمة طلب بحث في الطلب. يعرض الردّ قيم الحقول لرقم تعريف الملف.

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"
    }
  ]
}