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

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

يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل الاستجابة. بعد ذلك، يمكنك تمرير قناع حقل الاستجابة إلى أي من الطريقتين باستخدام معلَمة عنوان 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).

مثال على الرمز المميّز للمسار

في ما يلي مثال لنص طلب لمصدر واحد وطريق باتجاه واحد واستخدام أقنعة الحقل لطلب رمز مميز للمسار، بالإضافة إلى مدة المسار والمسافة والخط المتعدد للمسار:

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.