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

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

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

للحصول على معلومات حول مَعلمات النظام الأخرى التي تنطبق على Drive API، يُرجى الاطّلاع على مَعلمات النظام البديلة.

طريقة عمل المَعلمة fields

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

إذا لم تحدِّد المَعلمة fields، يعرض الخادم مجموعة تلقائية من الحقول الخاصة بالطريقة. على سبيل المثال، لا تعرض الطريقة list في الطريقة files سوى الحقول kind وid وname وmimeType. تعرض الطريقة get في المورد permissions مجموعة مختلفة من الحقول التلقائية.

بالنسبة إلى جميع طرق الموارد about وcomments (باستثناء delete) وreplies (باستثناء delete)، عليك ضبط المَعلمة fields. لا تعرض هذه الطرق مجموعة تلقائية من الحقول.

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

مَعلمات النظام البديلة

تم توثيق مَعلمات طلب البحث التي تنطبق على جميع عمليات Google Drive API في مَعلمات النظام.

مواضيع ذات صلة

• حلّ الأخطاء
• تحديد المشاكل في المصادقة والتفويض وحلّها
• تحسين الأداء