عند استدعاء الطريقة ComputeRoutes()، يجب تحديد الحقول التي تريد عرضها في الرد. يمكنك إجراء ذلك باستخدام قناع حقل استجابة، والذي يمكنك تقديمه مع مَعلمة عنوان URL $fields أو fields، أو باستخدام عنوان HTTP/gRPC X-Goog-FieldMask. لمزيد من المعلومات، يُرجى الاطّلاع على مَعلمات النظام.
قناع الحقل
قيمة قناع الحقل هي قائمة مسارات حقول مفصولة بفواصل. مسار كل حقل هو قائمة بأسماء الحقول مفصولة بنقاط وتمثّل التسلسل الهرمي للرسالة. اسم الحقل هو إما مفتاح عنصر JSON أو اسم علامة حقل protobuf. يبدأ مسار الحقل بنوع رسالة الرد على المستوى الأعلى، ويمكن أن يتبعه اختياريًا نقطة واحدة أو أكثر، ثم مستوى اسم الحقل التالي. بشكل عام، يتم إنشاء مسارات الحقول بالطريقة التالية:
topLevelField[.secondLevelField][.thirdLevelField][...]
قناع الحقل الخاص بالحالات الخاصة هو حرف البدل "*"، الذي يختار جميع الحقول على مستوى الجذر.
أمثلة
يوضّح المثال التالي كيفية ضبط أقنعة الحقول لطريقة ComputeRoutes().
مثال 1
قناع الحقل لجميع الحقول المتاحة (للفحص اليدوي)
X-Goog-FieldMask: *
مثال 2
قناع الحقل الخاص بالمدة والمسافة والمضلّع على مستوى المسار (مثال على إعداد الإنتاج)
X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline
ننصح بعدم استخدام قناع حقل الردّ الذي يتضمّن حرف البدل (*)، أو تحديد قناع الحقل على المستوى الأعلى (المسارات) في مرحلة الإنتاج. اختيار الحقول التي تحتاج إليها فقط:
يسمح لخادم Google بحفظ دورات المعالجة، ما يتيح لنا عرض نتائجك بوقت استجابة أقل.
يضمن أداءً ثابتًا لوقت الاستجابة. قد نضيف المزيد من حقول الردود في المستقبل، وقد تتطلّب هذه الحقول الجديدة وقتًا إضافيًا للمعالجة. في حال اختيار جميع الحقول، أو إذا اخترت جميع الحقول على المستوى الأعلى، قد ينخفض الأداء لأنّ أي حقل جديد نضيفه سيتم تضمينه تلقائيًا في ردّك.
تؤدي إلى حجم رد أصغر، ما يؤدي إلى زيادة معدل نقل البيانات على الشبكة.
لمزيد من المعلومات حول كيفية إنشاء مسارات الحقول، يُرجى الاطّلاع على field_mask.proto.