حساب مصفوفة مسار

هذا المنتج أو الميزة يتوفران في النسخة الحصرية (ما قبل التوفر للجمهور العام). قد يكون الدعم المقدّم للمنتجات والميزات في مرحلة ما قبل التوفّر للجمهور العام محدودًا، وقد لا تكون التغييرات التي يتم إجراؤها على المنتجات والميزات هنا متوافقة مع الإصدارات الأخرى من هذه المرحلة. تخضع عروض مرحلة ما قبل التوفّر للجمهور العام لبنود الخدمة المحدّدة في "منصة خرائط Google". لمزيد من المعلومات، يُرجى الاطّلاع على أوصاف مراحل الإطلاق.

يمكنك احتساب مسافة ومدة مسار لعدة نقاط بداية ووجهات باستخدام طريقة ComputeRouteMatrix في Routes Preferred API. يتيح ComputeRouteMatrix استخدام كل من مكالمات gRPC المتدفقة ومكالمات REST HTTP.

عند توفّر قائمة بأزواج من نقاط الانطلاق والوجهات، تحسب الدالة ComputeRouteMatrix المسافة ومدة الرحلة على طول مسار يبدأ من كل نقطة انطلاق وينتهي عند كل وجهة. يتوافق كل عنصر من عناصر مصدر البيانات مع معلومات مسار رحلة واحد.

تتضمّن طريقة ComputeRouteMatrix عدة مزايا مقارنةً بواجهة برمجة التطبيقات Distance Matrix API (الإصدار القديم):

• تتيح ميزة البث عرض العناصر قبل احتساب المصفوفة بأكملها، ما يقلّل من وقت الاستجابة.
• تتضمّن ComputeRouteMatrix خيارات دقيقة لاحتساب عدد الزيارات، ما يتيح لك اتّخاذ قرارات بشأن المفاضلة بين الجودة ووقت الاستجابة.
• يتم تنفيذ الطلبات بأولوية أعلى ضمن البنية الأساسية من Google، ما يؤدي إلى زيادة مدى التوفّر.
• يمكنك تحديد معلومات العنوان (اتجاه التنقّل) وجانب الطريق لنقاط الطريق.
• يمكنك طلب عرض معلومات عن رسوم المرور، بالإضافة إلى مسافة الطريق والوقت المقدّر للوصول.

تفعيل طريقة ComputeRouteMatrix

قبل أن تتمكّن من استخدام طريقة ComputeRouteMatrix في الرمز، عليك تفعيلها. لمزيد من المعلومات عن تفعيل طرق Routes Preferred API، يُرجى الاطّلاع على كيفية البدء.

ملاحظة مهمة: راجِع حدود الحصة لطُرق Routes Preferred API. إذا كنت بحاجة إلى زيادة حدود الحصة، يُرجى التواصل مع فريق الدعم من خلال تقديم طلب على صفحة دعم منصة خرائط Google في Google Cloud Console، أو من خلال الاتصال بخط المساعدة المباشر لفريق دعم Google Cloud.

استخدام طريقة ComputeRouteMatrix

تتوفّر طريقة ComputeRouteMatrix من خلال نقطة النهاية Routes Preferred v1.

للحصول على معلومات أكثر تفصيلاً، يمكنك الاطّلاع على المستندات التالية:

gRPC: https://developers.google.com/maps/documentation/routes_preferred/reference/rpc/google.maps.routes.v1

REST: https://developers.google.com/maps/documentation/routes_preferred/reference/rest/v1/TopLevel/computeRouteMatrix

توضّح الخطوات العامة التالية كيفية استخدام gRPC لاستدعاء الطريقة ComputeRouteMatrix:

1. راجِع بروتوكولات protobuffer اللازمة من مستودع googleapis:

   https://github.com/googleapis/googleapis/tree/master/google/maps/routes

   يُرجى العِلم أنّ بعض أنظمة الإنشاء، مثل Go، قد تنفّذ هذه العملية تلقائيًا نيابةً عنك.

2. باستخدام لغتك المفضّلة ومجموعة أدوات الإنشاء، أنشئ رمز protobuffer ذي الصلة.

3. إنشاء طلبك يجب إرسال جزأين من البيانات الوصفية المطلوبة مع الطلب:

   • يجب ضبط X-Goog-Api-Key على مفتاح واجهة برمجة التطبيقات.

   • يجب ضبط X-Goog-Fieldmask على قائمة حقول مفصولة بفواصل مطلوبة من الاستجابة. على سبيل المثال، X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status. يمكنك استخدام حرف البدل (*) للإشارة إلى جميع الحقول، ولكن لا يُنصح بذلك. استخدِم حرف البدل لاختبار وفهم استجابة واجهة برمجة التطبيقات، ولكن أدرِج الحقول التي تريدها بشكل صريح في قناع الحقل في رمز الإنتاج.

     لمزيد من المعلومات حول كيفية إنشاء سلسلة قناع الحقل، يُرجى الاطّلاع على https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto. يُرجى العِلم أنّ إيقاف الحقول التي لا تحتاج إليها يمكن أن يقلّل من وقت الاستجابة لأنّ هذه الحقول قد تتطلّب إجراء عمليات حسابية إضافية. ستبقى مدة الاستجابة ثابتة إذا حدّدت الحقول التي تحتاج إليها وأضفت لاحقًا حقولاً جديدة تتطلّب المزيد من العمليات الحسابية.

4. أرسِل طلبك إلى routespreferred.googleapis.com:443.يجب استخدام بروتوكول أمان طبقة النقل (TLS).

للاطّلاع على أمثلة حول استخدام طريقة ComputeRouteMatrix، راجِع أمثلة على احتساب مصفوفة الطرق (إصدار تجريبي).

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

لا نضمن عرض العناصر التي يعرضها البث بأي ترتيب. لهذا السبب، يحتوي كل عنصر على origin_index وdestination_index. بالنسبة إلى نقاط الانطلاق والوجهات المحدّدة في الطلب، تكون نقطة انطلاق المسار مكافئة origins[origin_index] لعنصر معيّن، وتكون وجهة المسار مكافئة destinations[destination_index]. تكون هذه الصفائف مفهرسة بدءًا من الصفر. من المهم تخزين ترتيبات قوائم المصدر والوجهة.

احتساب رسوم المرور

للحصول على معلومات حول طريقة احتساب رسوم العبور، يُرجى الاطّلاع على مقالة احتساب رسوم العبور.

للاطّلاع على أمثلة حول كيفية احتساب رسوم العبور، يُرجى الرجوع إلى أمثلة على احتساب مصفوفة الطرق.