عند استدعاء طريقة 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
لا ننصح باستخدام قناع حقل الاستجابة الذي يتضمّن حرف البدل (*) أو تحديد قناع الحقل في المستوى الأعلى (المسارات) في مرحلة الإنتاج. تحديد الحقول التي تحتاجها فقط:
يسمح ذلك لخادمنا بحفظ دورات المعالجة، ما يتيح لنا عرض نتائجك بوقت استجابة أقل.
يضمن أداءً مستقرًا لوقت الاستجابة. قد نضيف المزيد من حقول الاستجابة في المستقبل، وقد تتطلّب هذه الحقول الجديدة وقتًا إضافيًا للمعالجة. إذا اخترت جميع الحقول أو جميع الحقول في المستوى الأعلى، قد ينخفض مستوى الأداء لأنّ أي حقل جديد نضيفه سيتم تضمينه تلقائيًا في الردّ.
يؤدي ذلك إلى حجم استجابة أصغر، ما يعني معدل نقل بيانات أعلى في الشبكة.
لمزيد من المعلومات حول كيفية إنشاء مسارات الحقول، يُرجى الاطّلاع على field_mask.proto.