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

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

يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل الردّ. بعد ذلك تجتاز قناع حقل الاستجابة لأي من الطريقتين باستخدام معلمة عنوان 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 في الرد بالعودة.
• حساب أقنعة حقل مصفوفة المسارات
  • ‫REST: لتحديد حقول نص الاستجابة المطلوب عرضها
  • gRPC: يحدد حقول RouteMatrixElement كائن في الاستجابة للعودة.

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

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

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

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

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