اختيار المعلومات المطلوب عرضها
عند استدعاء طريقة لحساب مسار أو حساب مصفوفة مسار، عليك تحديد المعلومات التي تريدها من خلال تحديد الحقول التي تريد عرضها في الرد. لا توجد قائمة افتراضية للحقول المعروضة. إذا حذفت هذه القائمة، فستعرض الطرق خطأ.
يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل الاستجابة. ثم تمرّر قناع حقل الاستجابة إلى أي من الطريقتَين باستخدام معلَمة عنوان 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).
مثال على الرمز المميّز للمسار
في ما يلي مثال لنص طلب cURL لمسار أحادي الوجهة باستخدام أقنعة الحقول لطلب رمز مميَّز للمسار، بالإضافة إلى مدة المسار والمسافة والخطوط المتعددة للمسار:
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-Api-Key: YOUR_API_KEY' \ -H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
لمزيد من التفاصيل، يمكنك الاطّلاع على مرجع واجهة برمجة تطبيقات Compute Routes.