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

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

يوضّح هذا المستند كيفية استخدام المَعلمة fields في Google Drive.

آلية عمل مَعلمة fields

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

في حال عدم تحديد المَعلمة 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

الاستجابة

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