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

لعرض الحقول التي تحتاجها بالضبط وتحسين الأداء، استخدم 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". معلمة طلب البحث للحقول الصحيحة هذا المثال هو 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"
    }
  ]
}