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

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

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

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

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

تفعيل طريقة ComputeRouteMatrix

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

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

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

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

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. تحقَّق من مخازن البروتوكولات اللازمة من مستودع 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]. تكون هذه المصفوفات مفهرَسة بالصفر. من المهم تخزين ترتيبات قائمة المصدر والوجهة.

جارٍ احتساب رسوم العبور

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

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