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

عند استدعاء طريقة 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.