اختيار الحقول المراد إرجاعها

عند استدعاء الطريقة ComputeRoutes()، يجب تحديد الحقول التي تريد عرضها في الاستجابة. يمكنك إجراء ذلك باستخدام قناع حقل استجابة، والذي توفّره باستخدام مَعلمة عنوان URL $fields أو fields، أو باستخدام عنوان HTTP/gRPC X-Goog-FieldMask. لمزيد من المعلومات، يُرجى الاطّلاع على مَعلمات النظام.

قناع الحقل

قيمة قناع الحقل هي قائمة مفصولة بفواصل لمسارات الحقول. كل مسار حقل هو قائمة مفصولة بنقاط بأسماء الحقول التي تمثّل التسلسل الهرمي للرسالة. اسم الحقل هو إما مفتاح عنصر JSON أو اسم علامة حقل protobuf. يبدأ مسار الحقل من نوع رسالة الردّ من المستوى الأعلى، ويليه optionally نقطة واحدة أو أكثر، ثم المستوى التالي من اسم الحقل. بشكل عام، يتم إنشاء مسارات الحقول بالطريقة التالية:

topLevelField[.secondLevelField][.thirdLevelField][...]

قناع حقل الحالة الخاصة هو حرف نائب "*"، الذي يختار كل حقول مستوى الجذر.

أمثلة

يوضّح المثال التالي كيفية ضبط أقنعة الحقول لطريقة ComputeRoutes().

مثال 1

قناع حقل لجميع الحقول المتاحة (للفحص اليدوي)

X-Goog-FieldMask: *

مثال 2

قناع حقل للمدة والمسافة والخط المتعدّد على مستوى المسار (مثال على إعداد الإصدار العلني)

X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline

لا ننصح باستخدام قناع حقل الردّ البدل (*) أو تحديد قناع الحقل في المستوى الأعلى (المسارات) في مرحلة الإنتاج. اختيار الحقول التي تحتاج إليها فقط:

• يسمح هذا الإجراء لخادمنا بحفظ دورات المعالجة، ما يتيح لنا عرض النتائج بوقت استجابة أقل.

• ضمان أداء ثابت لوقت الاستجابة قد نضيف المزيد من حقول الردود في المستقبل، وقد تتطلّب هذه الحقول الجديدة وقتًا إضافيًا للمعالجة. إذا اخترت جميع الحقول، أو إذا اخترت جميع الحقول على المستوى الأعلى، قد تلاحظ تدهورًا في الأداء لأنّ أي حقل جديد نضيفه سيتم تضمينه تلقائيًا في ردّك.

• يؤدي ذلك إلى تقليل حجم الاستجابة، ما يؤدي إلى زيادة معدل نقل بيانات الشبكة.

لمزيد من المعلومات عن كيفية إنشاء مسارات الحقول، يُرجى الاطّلاع علىملف برمجي field_mask.proto.