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

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

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

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

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

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

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

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

بعد أن يعالج الخادم طلبًا صالحًا يتضمّن المَعلمة fields، يعرض رمز الحالة HTTP 200 OK مع البيانات المطلوبة. إذا كانت المَعلمة fields تحتوي على خطأ أو كانت غير صالحة، يعرض الخادم رمز الحالة HTTP 400 Bad Request مع رسالة خطأ توضّح المشكلة في الحقول التي اخترتها. على سبيل المثال، files.list(fields='files(id,capabilities,canAddChildren)') يؤدي إلى ظهور الخطأ "Invalid field selection 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/*' جميع حقول تفاصيل الإذن المتاحة لكل إذن. يُرجى العِلم أنّ استخدام حرف البدل يمكن أن يؤثّر سلبًا في أداء الطلب.

• لا يمكنك اختيار عناصر فردية من خريطة عندما تحتوي مفاتيحها على أحرف خاصة (مثل الشرطة المائلة / أو النقطة .). على سبيل المثال، تؤدي محاولة اختيار مفتاح تنسيق تصدير معيّن في exportLinks باستخدام fields=exportLinks/application/pdf إلى ظهور الخطأ HTTP 400 Bad Request لأنّ محلّل المسار يفسّر الرمز / على أنّه فاصل للسمات المُدمجة. لاسترداد أزواج المفاتيح والقيم التي تحتوي مفاتيحها على أحرف خاصة، اطلب الخريطة بأكملها (مثل fields=exportLinks) وفلتر النتائج من جهة العميل.

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)

لتحديد حقول مُدمجة ضمن مصفوفات أو كائنات مُدمجة، استخدِم أقواسًا مُدمجة. على سبيل المثال، لإدراج الملفات مع رقم تعريفها واسمها وتفاصيل مالكها المُدمجة (اسم العرض وعنوان البريد الإلكتروني) مع استرداد رمز الصفحة التالية للتقسيم على عدّة صفحات: files.list مع fields=nextPageToken,files(id,name,owners(displayName,emailAddress))

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 في مَعلمات النظام.

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

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