اختيار المعلومات المطلوب عرضها
عند استدعاء طريقة لحساب مسار أو لحساب مصفوفة مسار، ينبغي عليك تحديد المعلومات التي تريدها من خلال تحديد الحقول التي تريد عرضها في الرد. لا تتوفّر قائمة تلقائية للحقول المعروضة. إذا حذفت هذه القائمة، فستعرض الطرق خطأ.
يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل الاستجابة. بعد ذلك، يمكنك تمرير قناع حقل الاستجابة إلى أي من الطريقتين باستخدام معلَمة عنوان URL $fields
أو fields
أو من خلال استخدام عنوان HTTP أو عنوان gRPC X-Goog-FieldMask
.
إخفاء الحقول هو ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، مما يساعد على تجنب وقت المعالجة غير الضروري والرسوم التي يتم تحصيلها.
لمزيد من المعلومات عن مَعلمات عناوين URL، يُرجى الاطّلاع على مَعلمات النظام.
تحديد قناع حقل الاستجابة
قناع حقل الاستجابة هو قائمة مسارات مفصولة بفواصل، حيث يحدد كل مسار حقلاً فريدًا في رسالة الاستجابة. يبدأ المسار من رسالة استجابة المستوى الأعلى، ويستخدم مسارًا مفصولاً بنقاط إلى الحقل المحدّد.
أنشئ مسار حقل على النحو التالي:
topLevelField[.secondLevelField][.thirdLevelField][...]
- قناع حقل المسار
- أقنعة حقول مصفوفة المسار
- REST: تحدّد حقول نص الاستجابة المطلوب عرضها.
- gRPC: يحدّد حقول الكائن RouteMatrixElement في الاستجابة للعرض.
لمزيد من المعلومات حول طريقة إنشاء أقنعة الحقول، يُرجى الاطّلاع على field_mask.proto.
تحديد أقنعة الحقل التي يجب استخدامها
إليك كيفية تحديد أقنعة الحقول التي تريد استخدامها:
- اطلب جميع الحقول باستخدام قناع الحقل
*
. - اطّلِع على التسلسل الهرمي للحقول في الإجابة وحدِّد الحقول التي تريدها.
- يمكنك إنشاء قناع الحقل باستخدام التسلسل الهرمي للحقل.
على سبيل المثال، بالنسبة إلى هذه الاستجابة الجزئية من مسار نقل عام:
"routes": [ { "legs": [ { "distanceMeters": 12886, } ... ]}]
إذا كنت تريد عرض الحقل distanceMeters
فقط، سيكون قناع الحقل هو:
routes.legs.distanceMeters
مثال آخر: لعرض كل شيء ضمن legs
في الاستجابة، يكون قناع الحقل هو:
routes.legs
تحديد مسار الحقل
يحتوي هذا القسم على أمثلة حول كيفية تحديد مسار حقل كجزء من قناع حقل الاستجابة.
مكالمة REST على الرقم computeRoutes
في المثال الأول، يمكنك استخدام طلب REST لطريقة computeRoutes
لاحتساب المسار. في هذا المثال، يمكنك تحديد أقنعة الحقول لعرض الحقلَين
Route.distanceMeters
وRoute.duration
في الاستجابة. تذكَّر أن تضع routes
بادئة لاسم الحقل.
-H X-Goog-FieldMask: routes.distanceMeters,routes.duration
مكالمة REST على الرقم computeRouteMatrix
بالنسبة إلى طريقة REST computeRouteMatrix
المستخدَمة لحساب مصفوفة مسار، حدِّد في العنوان عرض
originIndex
وdestinationIndex
وduration
لكل مجموعة من المصدر
والوجهة:
-H X-Goog-FieldMask: originIndex,destinationIndex,duration
طلب gRPC
بالنسبة إلى gRPC، اضبط متغيّرًا يحتوي على قناع حقل الاستجابة. يمكنك بعد ذلك تمرير هذا المتغير إلى الطلب.
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
اعتبارات مسار الحقل
قم بتضمين الحقول التي تطلبها في الرد فقط. إرجاع الحقول التي تحتاجها فقط:
- يقلل من أوقات المعالجة، بحيث يتم عرض نتائجك بوقت استجابة أقل.
- ضمان أداء وقت استجابة ثابت إذا أضافت واجهة برمجة التطبيقات المزيد من حقول الاستجابة في المستقبل، وكانت هذه الحقول الجديدة تتطلّب وقتًا إضافيًا للحساب. إذا اخترت جميع الحقول، أو إذا اخترت جميع الحقول في المستوى الأعلى، قد تشهد تراجعًا في الأداء عند تضمين جميع الحقول الجديدة تلقائيًا في إجابتك.
- يؤدي ذلك إلى صغر حجم الاستجابة، ما يؤدي إلى زيادة سرعة معالجة البيانات على الشبكة.
- تأكّد من عدم طلب بيانات غير ضرورية، ما يساعد على تجنُّب وقت المعالجة غير الضروري والرسوم التي يتم تحصيلها من خلال الفواتير.
طلب الرمز المميّز للمسار
لطلب عرض Routes API للرموز المميّزة للمسارات التي تمّ إنشاؤها، اتّبِع
متطلبات عرض الرمز المميّز للمسار، ثم استخدِم
قناع الحقل routes.route_token
لطلب الرمز المميّز:
- اضبط السمة
travel_mode
علىDRIVING
. - اضبط
routing_preference
علىTRAFFIC_AWARE
أوTRAFFIC_AWARE_OPTIMAL
. - تأكد من عدم وجود أي من نقاط الطريق في المسار لا تمثل
via
نقاط مسار. - حدِّد قناع حقل الرمز المميّز للمسار:
-H X-Goog-FieldMask: routes.route_token
يمكنك استخدام المسار المخطط له في حزمة تطوير البرامج (SDK) للتنقل. لمزيد من التفاصيل، راجِع تخطيط مسار (نظام التشغيل Android) أو تخطيط مسار (نظام التشغيل iOS).
مثال على الرمز المميّز للمسار
في ما يلي مثال لنص طلب لمصدر واحد وطريق باتجاه واحد واستخدام أقنعة الحقل لطلب رمز مميز للمسار، بالإضافة إلى مدة المسار والمسافة والخط المتعدد للمسار:
terminal curl -X POST -d {"origin":{ "location": { "latLng":{ "latitude": -37.8167, "longitude": 144.9619 } } }, "destination":{ "location": { "latLng":{ "latitude":-37.8155, "longitude": 144.9663 } } }, "routingPreference":"TRAFFIC_AWARE", "travelMode":"DRIVE" } -H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
لمزيد من التفاصيل، اطّلِع على مرجع واجهة برمجة تطبيقات Compute Routes.