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

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