ما هي أهمية نقل البيانات إلى Routes API؟

توفّر Routes API أداءً محسّنًا لاحتساب الاتجاهات والمسافة ومدة الرحلة، ما يجعلها بديلاً مناسبًا للتطبيقات التي تستخدم Directions API وDistance Matrix API. تتوافق معظم وظائف Routes API مع الأنظمة القديمة لكل من Directions API وDistance Matrix API.

استخدِم هذا الدليل للتعرّف على الاختلافات الرئيسية في Routes API مقارنةً بالمنتجات التي تحلّ محلّها، بالإضافة إلى كيفية التعامل مع التغييرات اللازمة. لمزيد من التفاصيل حول ميزات Routes API الأخرى، يُرجى الاطّلاع على نظرة عامة على المنتج.

التحسينات الرئيسية

يتناول هذا القسم بعض التحسينات التي يمكنك توقّعها عند استخدام واجهة Routes API في تطبيقاتك.

سقف أعلى للطلبات

Routes API Compute Route Matrix	‫625 عنصر كحدّ أقصى، ما لم تحدّد TRAFFIC_AWARE_OPTIMAL. يمكنك إضافة 100 عنصر كحدّ أقصى باستخدام TRAFFIC_AWARE_OPTIMAL. اطّلِع على إعدادات التوجيه المحسّنة. يمكن استخدام 50 نقطة طريق (نقاط بداية + وجهات) كحدّ أقصى باستخدام رقم تعريف المكان.
Distance Matrix API	يمكن إضافة 25 مصدرًا أو 25 وجهة بحد أقصى لكل طلب. الحد الأقصى هو 100 عنصر (عدد المصادر × عدد الوجهات) لكل طلب من جهة الخادم.

ردود أسرع على الطلبات

توفّر ميزة "مصفوفة مسارات الحوسبة" تحسينات زمن الاستجابة التالية:

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

تحسينات التوجيه

توفّر ميزة "احتساب المسار" تحسينات التوجيه التالية:

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

طلب البيانات التي تحتاجها فقط

يمكنك الآن تحديد الحقول التي تريد عرضها، ما يقلّل من وقت المعالجة ورسوم الفوترة.

Routes API Compute Routes Compute Route Matrix	يجب أن تستخدم طلباتك قناع حقل لتحديد الحقول التي تريد عرضها في الرد. يضمن إخفاء الحقول عدم طلب بيانات غير ضرورية، ما يجنّبك وقت المعالجة ورسوم الفوترة غير الضرورية. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة اختيار الحقول المطلوب عرضها.
Directions API Distance Matrix API	تعرض هذه السمة قائمة تلقائية بالحقول، حتى إذا كان تطبيقك لا يحتاج إليها بشكل صارم. ويمكن أن يؤدي ذلك إلى إضاعة وقت المعالجة وتحمّل رسوم فوترة غير ضرورية.

تحسين عمليات احتساب المسارات المتعلقة بحركة المرور

تتيح واجهة Routes API ثلاثة إعدادات مفضّلة للتوجيه يمكنك استخدامها لتحقيق التوازن بين وقت استجابة الطلب وجودة البيانات عند طلب معلومات حول حركة المرور.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة ضبط الجودة مقابل وقت الاستجابة.

TRAFFIC_UNAWARE (تلقائي)	يستخدم متوسط بيانات حركة المرور غير المرتبطة بالوقت، وليس بيانات حركة المرور المباشرة، لحساب المسار، ما يؤدي إلى أقل وقت استجابة. هذا الخيار مكافئ للحالة التي لا يتم فيها استخدام بيانات حركة المرور في كل من Directions API وDistance Matrix API.
TRAFFIC_AWARE (جديد)	جودة بيانات حركة المرور المباشرة محسّنة الأداء لتقليل وقت الاستجابة على عكس TRAFFIC_AWARE_OPTIMAL، يطبّق هذا الإعداد تحسينات لتقليل وقت الاستجابة بشكل كبير. هذا الإعداد جديد أيضًا في واجهة Routes API ولا يتوفّر أي إعداد مماثل في واجهة Directions API أو واجهة Distance Matrix API.
TRAFFIC_AWARE_OPTIMAL	بيانات حركة مرور شاملة وعالية الجودة يؤدي هذا الإعداد إلى أعلى وقت استجابة، وهو يعادل الإعداد departure_time في Directions API وDistance Matrix API. هذا الخيار يعادل الوضع الذي يستخدمه maps.google.com وتطبيق "خرائط Google" للأجهزة الجوّالة.

مقارنة احتساب المسارات

يقارن الجدول التالي بين خيارات التوجيه في كل من Routes API وDirections API وDistance Matrix API.

خيار حركة المرور	Routes API	Directions API Distance Matrix API	وقت الاستجابة
ما مِن زيارات في الوقت الفعلي	TRAFFIC_UNAWARE	لم يتم ضبط السمة departure_time	أسرع وقت استجابة بين الأوضاع الثلاثة
تم تطبيق أحوال حركة المرور مباشرةً	TRAFFIC_AWARE	بدون مكافئ	وضع جديد أضافته واجهة Routes API. ويوفّر وقت استجابة أكبر قليلاً من TRAFFIC_UNAWARE مع تكلفة بسيطة لجودة الوقت المقدَّر للوصول. تكون مدة الاستجابة أقل بكثير من TRAFFIC_AWARE_OPTIMAL.
بيانات حركة المرور في الوقت الفعلي شاملة وعالية الجودة	TRAFFIC_AWARE_OPTIMAL	مجموعة مواقع (departure_time)	وهي تعادل الوضع المستخدَم في maps.google.com وفي تطبيق "خرائط Google" للأجهزة الجوّالة. بالنسبة إلى Compute Route Matrix، لا يمكن أن يتجاوز عدد العناصر في الطلب (عدد نقاط الانطلاق × عدد الوجهات) 100 عنصر.

الاختلافات الرئيسية

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

الاتصال بخدمة واحدة بدلاً من اثنتين

Routes API	فعِّل خدمة واحدة فقط في API Console ليتمكّن تطبيقك من استخدام Compute Routes وCompute Route Matrix. لمزيد من المعلومات، يُرجى الاطّلاع على الإعداد في وحدة تحكّم Google API.
Directions API Distance Matrix API	فعِّل خدمتين: Directions API وDistance Matrix API كخدمتَين منفصلتَين في وحدة تحكّم واجهة برمجة التطبيقات.

طلبات استخدام HTTPS POST

Routes API	يمكنك تمرير المَعلمات في نص الطلب أو في العناوين كجزء من طلب HTTP POST. للاطّلاع على أمثلة، يُرجى الرجوع إلى: - حساب مسار - حساب مصفوفة مسارات
Directions API Distance Matrix API	مرِّر مَعلمات عنوان URL باستخدام طلب HTTP GET.

الاختلافات في الردود المتعلّقة بالوقت المقدّر للوصول

تعرض واجهة Routes API الوقت المقدَّر للوصول وتستخدم السمة duration في الاستجابة بشكل مختلف عن خدمات Directions API وDistance Matrix API، كما هو موضّح في الجدول أدناه.

نوع ETA	Routes API	Directions API Distance Matrix API
الوقت المقدَّر للوصول غير مرتبط بحركة المرور وغير معتمد على الوقت	اضبط الإعدادات باستخدام TRAFFIC_UNAWARE. الوقت المقدَّر للوصول الوارد في سمة الاستجابة duration تحتوي سمتَا الاستجابة duration وstaticDuration على القيمة نفسها.	يتوافق مع عدم ضبط departure_time في الطلب. الوقت المقدّر للوصول مضمّن في سمة الردّ duration. لا يتم عرض سمة الرد duration_in_traffic.
الوقت المقدَّر للوصول الذي يأخذ في الاعتبار حركة المرور في الوقت الفعلي	اضبط القيمة باستخدام TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL. يتم تضمين الوقت المقدَّر للوصول الذي يأخذ في الاعتبار حركة المرور في الوقت الفعلي في سمة الاستجابة duration. يحتوي عنصر staticDuration response على مدة التنقّل على طول المسار بدون أخذ حالة حركة المرور في الاعتبار. لم تعُد السمة duration_in_traffic تظهر في النتائج.	اضبط القيمة باستخدام departure_time في الطلب. يتم تضمين الوقت المقدَّر للوصول مع مراعاة حركة المرور في الوقت الفعلي في السمة duration_in_traffic في الاستجابة.

نقاط طريق الخطوط المتعددة

لم يعُد عليك تحويل إحداثيات خطوط الطول والعرض إلى نقاط طريق متعددة الخطوط باستخدام هذه الخدمة التي تتوافق مع نص طلب POST، وبالتالي لم يعُد هناك أي تأثير لحدود سلسلة عناوين URL. حلّ بعض مستخدمي Distance Matrix API مشكلة حدود الطلبات من خلال تحويل نقاط خطوط الطول والعرض إلى نقاط طريق متعددة الخطوط.

العناوين المنسَّقة (عكس الترميز الجغرافي)

لا توفّر واجهة Routes API عناوين منسَّقة في الردّ. للحصول على عناوين منسَّقة، استخدِم Geocoding API المصمَّمة لحالة الاستخدام هذه والتي توفّر نتائج بجودة أعلى.

وسائل النقل المتاحة

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

تنسيق XML للردود

لا توفّر واجهة Routes API ملف XML كتنسيق للرد. يمكنك العثور على عدد من أدوات تحويل JSON إلى XML على الإنترنت والتي من المفترض أن تناسب أغراضك.