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

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

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

التحسينات الأساسية

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

حدود متزايدة للطلبات

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يقارن الجدول التالي بين خيارات التوجيه بين خدمات Routes API وDirections API وواجهة برمجة تطبيقات مصفوفة المسافة.

خيار حركة المرور Routes API واجهة برمجة تطبيقات الاتجاهات
واجهة برمجة تطبيقات مصفوفة المسافة		 استغرق الرد وقتًا طويلاً
لا توجد حركة مرور في الوقت الفعلي TRAFFIC_UNAWARE لم يتم ضبط سمة واحدة (departure_time). وقت الاستجابة الأسرع بين الأوضاع الثلاثة
تم تطبيق أحوال حركة المرور المباشرة. TRAFFIC_AWARE بدون مكافئ

تمت إضافة وضع جديد من خلال Routes API. ويتطلّب ذلك وقت استجابة أكبر قليلاً من TRAFFIC_UNAWARE، بتكلفة بسيطة للوقت المقدر للوصول.

وقت الاستجابة أقل بكثير من TRAFFIC_AWARE_OPTIMAL.
يتم تطبيق بيانات عالية الجودة وشاملة عن الزيارات المباشرة. TRAFFIC_AWARE_OPTIMAL مجموعة مواقع واحدة (departure_time)

تعادل هذه الإعدادات الوضع المستخدَم في maps.google.com وتطبيق "خرائط Google" المتوافق مع الأجهزة الجوّالة.

بالنسبة إلى مصفوفة مسارات الحوسبة، لا يمكن أن يتجاوز عدد العناصر في الطلب (عدد المصادر × عدد الوجهات) 100 عنصر.

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

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

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

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

تستهلك HTTPS POST طلبات.

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

الاختلافات في الردود النصية الموسَّعة

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

نوع الوقت المقدّر للوصول Routes API واجهة برمجة تطبيقات الاتجاهات
واجهة برمجة تطبيقات مصفوفة المسافة
حركة المرور الوقت المقدر للوصول غير المدرك ولا تختلف عن الوقت

يتم الضبط باستخدام TRAFFIC_UNAWARE.

  • الوقت المقدر للوصول مضمّنة في سمة الاستجابة duration.
  • تحتوي سمتا الاستجابة duration وstaticDuration على القيمة نفسها.

يطابِق السمة departure_time التي لم يتم ضبطها في الطلب.

  • الوقت المقدر للوصول مضمّنة في سمة الاستجابة duration.
  • ولا يتم عرض سمة الاستجابة duration_in_traffic.
الوقت المقدّر للوصول الذي يأخذ في الاعتبار كثافة حركة المرور في الوقت الفعلي.

اضبط السمة باستخدام TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL.

  • وتجدر الإشارة إلى أنّ الوقت المقدّر للوصول مع أخذ الزيارات في الوقت الفعلي في الاعتبار مضمّنة في سمة الاستجابة duration.
  • تحتوي سمة الاستجابة staticDuration على مدة التنقّل خلال المسار بدون مراعاة أحوال حركة المرور.
  • لم تعُد السمة duration_in_traffic تُعرَض.

يتم الضبط باستخدام departure_time في الطلب.

  • وتجدر الإشارة إلى أنّ الوقت المقدّر للوصول مع أخذ الزيارات في الوقت الفعلي في الاعتبار مضمّنة في سمة الاستجابة duration_in_traffic.

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

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

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

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

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

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

XML كتنسيق رد

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