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

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

يمكنك تحديد قائمة الحقول من خلال إنشاء قناع حقل استجابة. بعد ذلك، يمكنك تمرير قناع حقل الاستجابة إلى أي من الطريقتَين باستخدام مَعلمة عنوان 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 المرتبطة في القائمة التالية. حدِّد الحقول بتنسيق camel case كما هو موضّح في المرجع. مثلاً: routePreference

وفي المقابل، يجب إدخال قيم المعلمات كما هو موضّح. على سبيل المثال، يجب إدخال TRAFFIC_AWARE بدلاً من routingPreference.

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

• قناع حقل المسار
  • ‫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 REST المستخدَمة لاحتساب مصفوفة المسارات، حدِّد في العنوان عرض originIndex وdestinationIndex وduration لكلّ تركيبة من نقطة المغادرة والوجهة:

X-Goog-FieldMask: originIndex,destinationIndex,duration

مكالمة gRPC

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

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

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

أدرِج فقط الحقول التي تحتاج إليها في الردّ لعرض الحقول التي تحتاج إليها فقط:

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

ملاحظة: عند تحليل رسالة استجابة، إذا كان أحد الحقول في رسالة الاستجابة يحتوي على قيمته التلقائية، قد يتم حذف الحقل من الاستجابة حتى إذا حدّدته في قناع حقل الاستجابة. لمزيد من المعلومات، يُرجى الاطّلاع على دليل اللغة (proto3). على سبيل المثال، عند احتساب مصفوفة مسار، يمكن أن يحتوي الحقل distanceMeters في الاستجابة على القيمة 0، وهي القيمة التلقائية. ولأن 0 هي القيمة التلقائية لـ distanceMeters، يتم حذفها من الردّ.

لمزيد من التفاصيل حول إنشاء قناع حقل، يُرجى الاطّلاع علىملف 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.