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

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

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

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

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

زيادة الحدود القصوى المسموح بها للطلبات

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

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

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

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

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

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

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

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

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

Routes API يجب أن تستخدم طلباتك قناع حقل لتحديد الحقول التي تريد عرضها في الاستجابة. تضمن لك ميزة إخفاء الحقول عدم طلب data غير ضرورية، ما يتجنّب وقت المعالجة والفواتير غير الضرورية.
لمزيد من المعلومات، يُرجى الاطّلاع على اختيار الحقول التي سيتم عرضها.
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_UNAWARE مع تكلفة صغيرة لجودة وقت الوصول المقدَّر.

ويكون وقت استجابةه أقل بكثير من TRAFFIC_AWARE_OPTIMAL.
تطبيق بيانات شاملة وعالية الجودة لحركة المرور في الوقت الفعلي TRAFFIC_AWARE_OPTIMAL مجموعة خصائص departure_time

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

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

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

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

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

Routes API فعِّل خدمة واحدة فقط في وحدة تحكّم واجهة برمجة التطبيقات لتطبيقك من أجل استخدام Compute Routes وCompute Route Matrix.
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الإعداد في وحدة تحكّم واجهة برمجة التطبيقات في Google.
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 كما هو موضّح في الجدول أدناه.

نوع وقت الوصول المقدَّر 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 على مدّة التنقّل في المسار بدون مراعاة ظروف حركة المرور.
  • لم تعُد سمة 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 على الإنترنت التي من المفترض أن تناسب أغراضك.