اختيار المعلومات التي تريد عرضها

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

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

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

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

تحديد قناع حقل الردّ

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

يمكنك إنشاء مسار حقل وتحديده على النحو التالي:

  1. ابحث عن الحقول التي تحتوي على المعلومات التي تحتاجها من Routes API. لمعرفة التفاصيل، يُرجى الاطّلاع على مراجع الحقول.
  2. تحديد مسارات الحقول التي تحتاج إليها وإنشاء أقنعة حقول لها: لمعرفة التفاصيل، يُرجى الاطّلاع على تحديد قناع الحقل الذي تريد استخدامه.

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

    routes.legs.distanceMeters,routes.legs.steps.duration

  4. أرسِل قناع الحقل مع طلب البيانات من واجهة برمجة التطبيقات. على سبيل المثال، في طلب cURL، يمكنك تحديد قناع الحقل باستخدام -H وX-Goog-FieldMask:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
للاطّلاع على أمثلة ومزيد من التفاصيل، يمكنك الاطّلاع على الأقسام التالية.

المراجع الميدانية

لعرض الحقول التي يمكنك طلبها في ردّ من خلال أقنعة الحقول، راجِع مراجع Routes API المرتبطة في القائمة التالية. حدِّد الحقول في حالة الجمل كما هو موضّح في المرجع. مثلاً: routePreference

تتضمن هذه المراجع الحقول المتاحة؛ ومع ذلك، تحتاج إلى الرجوع إلى التسلسل الهرمي للحقول لتحديد مسار قناع الحقل بالكامل. لمعرفة تفاصيل عن الحصول على التسلسل الهرمي للحقول، يُرجى الاطّلاع على تحديد قناع الحقل الذي تريد استخدامه.

  • حساب قناع حقل المسار
    • REST: تحدد حقول الكائن Route في الردّ الذي يتم إرجاعه، مسبوقًا بـ routes.، على سبيل المثال: routes.distanceMeters
    • gRPC: يحدد حقول الكائن Route في الرد بالعودة.
  • حساب أقنعة حقل مصفوفة المسارات

تحديد أقنعة الحقل المراد استخدامها

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

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

  3. إنشاء أقنعة الحقل باستخدام التدرج الهرمي للحقول المعروضة في الخطوة السابقة، باستخدام التنسيق التالي:

    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 طريقة مستخدمة لحساب مصفوفة مسار، في العنوان، حدد طريقة إرجاع originIndex وdestinationIndex وduration لكل مجموعة من المصادر والوجهة:

X-Goog-FieldMask: originIndex,destinationIndex,duration

مكالمة gRPC

بالنسبة إلى gRPC، اضبط متغيّرًا يحتوي على قناع حقل الاستجابة. يمكنك بعد ذلك تمرير هذا المتغير إلى الطلب.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

اعتبارات مسار الحقل

لا تضمِّن سوى الحقول التي تحتاجها في الرد لعرض الحقول التي تحتاجها:

  • يقلل من أوقات المعالجة، حتى يتم عرض نتائجك في وقت استجابة أقل.
  • ضمان أداء وقت الاستجابة المستقر: إذا كنت جميع الحقول، أو إذا حددت جميع الحقول في المستوى الأعلى، يمكنك تدهور الأداء عند إضافة حقول جديدة ثم إضافة تضمينها تلقائيًا في ردك.
  • ينتج عن ذلك حجم استجابة أصغر، ما يترجم إلى زيادة سرعة معالجة بيانات الشبكة.
  • يضمن عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة غير الضروري والرسوم التي يتم تحرير فواتير بها.

لمزيد من التفاصيل حول إنشاء قناع حقل، يمكنك الاطلاع على field_mask.proto.

طلب رمز مميز للمسار

لطلب إرجاع Routes API الرموز المميّزة للمسارات التي تمّ إنشاؤها، اتّبِع الخطوات التالية:

  1. اضبط المعلمات التالية المطلوبة لعرض رمز مميز للمسار:
    • اضبط السمة travelMode على DRIVE.
    • اضبط السمة routingPreference على TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL.
  2. تأكَّد من أنّ جميع نقاط الطريق ليست ضمن via نقطة.
  3. حدِّد قناع الحقل routes.routeToken لعرض رمز مميّز للمسار: 
    X-Goog-FieldMask: routes.routeToken

ويمكنك استخدام الرمز المميّز للمسار لمسارك المُخطَّط له في حزمة تطوير البرامج للتنقل. لمزيد من التفاصيل، يُرجى مراجعة التخطيط لمسار (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.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

لمزيد من التفاصيل، يُرجى مراجعة مرجع Compute Routes API