اختيار الحقول المطلوب عرضها
عند طلب مسار أو مصفوفة مسار، يجب استخدام قناع حقل لتحديد المعلومات التي يجب أن يعرضها الردّ. لا تتوفّر قائمة تلقائية بالحقول المعروضة. إذا لم تحدِّد قناع حقل، ستعرِض الطرق خطأ.
يضمن استخدام قناع حقل أيضًا عدم طلب بيانات غير ضرورية، ما يساعد بدوره في تقليل وقت الاستجابة وتجنُّب الرسوم غير الضرورية مقابل معلومات لا يحتاج إليها نظامك.
يمكنك تحديد قائمة الحقول التي تحتاج إليها في قناع حقل الاستجابة. بعد ذلك، يمكنك تمرير
قناع حقل الاستجابة إلى أي من الطريقتَين باستخدام مَعلمة عنوان URL $fields
أو
fields
، أو باستخدام عنوان HTTP أو gRPC X-Goog-FieldMask
.
لمزيد من المعلومات عن مَعلمات عناوين URL، اطّلِع على مَعلمات النظام.
تحديد قناع حقل ردّ
قناع حقل الاستجابة هو قائمة مفصولة بفواصل بالمسارات، حيث يحدّد كل مسار حقلًا فريدًا في رسالة الاستجابة. يبدأ المسار من رسالة الاستجابة ذات المستوى الأعلى ويستخدم مسارًا مفصولاً بنقاط إلى الحقل المحدّد.
أنشئ مسار حقل وحدِّده على النحو التالي:
- ابحث عن الحقول التي تحتوي على المعلومات التي تحتاجها من Routes API. لمعرفة التفاصيل، يُرجى الاطّلاع على مراجع الحقول.
- تحديد مسارات الحقول التي تحتاج إليها وإنشاء أقنعة الحقول لها: لمعرفة التفاصيل، اطّلِع على تحديد قناع الحقل الذي تريد استخدامه.
ادمج أقنعة الحقول لجميع الحقول التي تحتاج إليها، مع الفصل بين أقنعة الحقول بفواصل. على سبيل المثال، لطلب
distanceMeters
لمرحلة المسار، بالإضافة إلى المدة لكل خطوة من خطوات مرحلة المسار، أدخِل كلاهما مفصولَين بفاصلة بدون أي مسافات:routes.legs.distanceMeters,routes.legs.steps.duration
أرسِل قناع الحقل مع طلب بيانات من واجهة برمجة التطبيقات. على سبيل المثال، في طلب cURL، يمكنك تحديد قناع الحقل باستخدام
-H
وX-Goog-FieldMask
:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
مراجع الحقول
للاطّلاع على الحقول التي يمكنك طلبها في ردّ من خلال أقنعة الحقول، راجِع مراجع Routes API المرتبطة في القائمة التالية. حدِّد الحقول بتنسيق camel case كما هو موضّح في المرجع. مثلاً: routePreference
تتضمّن هذه الإشارات الحقول المتاحة، ولكن عليك الرجوع إلى التسلسل الهرمي للحقول لتحديد مسار قناع الحقل الكامل. للاطّلاع على تفاصيل عن الحصول على التدرّج الهرمي للحقول، اطّلِع على تحديد قناع الحقل الذي تريد استخدامه.
- قناع حقل مسار الحساب
- حساب أقنعة حقول مصفوفة المسار
- REST: لتحديد حقول نص الاستجابة المطلوب عرضها
- gRPC: لتحديد حقول كائن RouteMatrixElement في الاستجابة المراد عرضها.
تحديد أقنعة الحقول التي تريد استخدامها
في ما يلي كيفية تحديد الحقول التي تريد استخدامها وإنشاء أقنعة الحقول لها:
- طلب جميع الحقول باستخدام قناع حقل
*
- اطّلِع على التسلسل الهرمي للحقول في الاستجابة للحقول التي تريدها.
أنشئ أقنعة الحقول باستخدام التسلسل الهرمي للحقول المعروضة في الخطوة السابقة، باستخدام التنسيق التالي:
topLevelField[.secondLevelField][.thirdLevelField][...]
على سبيل المثال، في ما يتعلّق بهذا الردّ الجزئي من مسار:
"routes": [ { "legs": [ { "steps": [ {"distanceMeters": 119}, {"distanceMeters": 41} ] } ], "distanceMeters": 160 } ]
إذا كنت تريد عرض حقل distanceMeters
فقط لمرحلة المسار، أي distanceMeters
الأخير في العيّنة السابقة، يكون قناع الحقل على النحو التالي:
routes.legs.distanceMeters
إذا أردت بدلاً من ذلك عرض حقل distanceMeters
لكل خطوة من خطوات مسار الرحلة، أي distanceMeters
ضمن steps
في العيّنة السابقة، يكون قناع الحقل على النحو التالي:
routes.legs.steps.distanceMeters
إذا أردت عرض كليهما، مع النتيجة أعلاه، يكون قناع الحقل على النحو التالي:
routes.legs.distanceMeters,routes.legs.steps.distanceMeters
أمثلة على مسارات قناع الحقل
يحتوي هذا القسم على المزيد من الأمثلة حول كيفية تحديد مسار حقل كجزء من قناع حقل استجابة في طلبات REST وgRPC.
طلب REST إلى computeRoutes
في المثال الأول، يتم استخدام طلب REST للطريقة
computeRoutes
لاحتساب
مسار. في هذا المثال، في العنوان، يمكنك تحديد أقنعة الحقول لعرض حقلَي المسار distanceMeters
وduration
في الاستجابة. تذكَّر إضافة routes
قبل اسم الحقل.
X-Goog-FieldMask: routes.distanceMeters,routes.duration
طلب REST إلى computeRouteMatrix
بالنسبة إلى طريقة computeRouteMatrix
REST المستخدَمة لاحتساب مصفوفة المسارات، حدِّد في العنوان عرض
originIndex
وdestinationIndex
وduration
لكل مجموعة من نقطة المغادرة
والوجهة:
X-Goog-FieldMask: originIndex,destinationIndex,duration
مكالمة gRPC
بالنسبة إلى gRPC، اضبط متغيّرًا يحتوي على قناع حقل الاستجابة. ويمكنك بعد ذلك تمرير هذا المتغيّر إلى الطلب.
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
اعتبارات مسار الحقل
أدرِج فقط الحقول التي تحتاج إليها في الاستجابة لعرض الحقول التي تحتاج إليها فقط:
- تقليل أوقات المعالجة، وبالتالي عرض النتائج بسرعة استجابة أقل
- ضمان أداء ثابت لوقت الاستجابة إذا اخترت جميع الحقول، أو إذا اختَرت جميع الحقول في المستوى الأعلى، قد يؤدي ذلك إلى انخفاض الأداء عند إضافة حقول جديدة ثم يتم تضمينها تلقائيًا في ردّك.
- تؤدي إلى تقليل حجم الاستجابة، ما يؤدي إلى زيادة معدل نقل البيانات في الشبكة.
- ضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب الوقت غير الضروري الذي تستغرقه المعالجة والرسوم التي يتم تحصيلها
لمزيد من التفاصيل حول إنشاء قناع حقل، يُرجى الاطّلاع علىملف field_mask.proto.