اختيار المعلومات المطلوب عرضها

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

يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل الاستجابة. ثم تمرّر قناع حقل الاستجابة إلى أي من الطريقتَين باستخدام معلَمة عنوان URL $fields أو fields أو باستخدام عنوان HTTP أو gRPC X-Goog-FieldMask.

إخفاء الحقول هو ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، مما يساعد على تجنب وقت المعالجة غير الضروري والرسوم التي تفرضها الفاتورة.

لمزيد من المعلومات عن مَعلمات عناوين URL، يُرجى الاطّلاع على مَعلمات النظام.

تحديد قناع حقل الاستجابة

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

أنشِئ مسار حقل على النحو التالي:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • احتساب قناع حقل المسار
    • REST: تحدّد حقول كائن Route في الاستجابة للعودة، مسبوقة بـ routes.، على سبيل المثال، routes.distanceMeters.
    • gRPC: يحدد حقول كائن Route في الاستجابة للعرض.
  • حساب أقنعة حقول مصفوفة المسار

لمزيد من المعلومات حول طريقة إنشاء أقنعة الحقول، راجِع field_mask.proto.

تحديد أقنعة الحقول المطلوب استخدامها

إليك كيفية تحديد أقنعة الحقول التي تريد استخدامها:

  1. اطلب جميع الحقول باستخدام قناع الحقل *.
  2. اطّلِع على التسلسل الهرمي للحقول في الردّ وحدِّد الحقول التي تريدها.
  3. يمكنك إنشاء قناع الحقل باستخدام التسلسل الهرمي للحقل.

على سبيل المثال، بالنسبة إلى هذه الاستجابة الجزئية من مسار نقل عام:

 "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 لطلب الرمز المميّز:

  1. اضبط السمة travel_mode على DRIVING.
  2. اضبط السمة routing_preference على TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL.
  3. تأكد من أن جميع نقاط الطريق في المسار لا تكون via نقطة.
  4. حدِّد قناع حقل الرمز المميّز للمسار: 
    -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.