Method: computeRouteMatrix

تأخذ هذه الشبكة قائمة بالمصادر والوجهات وتعرض مصدر بيانات يحتوي على معلومات المسار لكل مجموعة من نقطة الانطلاق والوجهة.

ملاحظة: تتطلب هذه الطريقة تحديد قناع حقل الردّ في الإدخال. يمكنك توفير قناع حقل الاستجابة باستخدام مَعلمة عنوان URL $fields أو fields أو باستخدام عنوان HTTP/gRPC X-Goog-FieldMask (اطّلِع على عناوين وعناوين URL المتوفّرة). ويجب أن تكون القيمة هي قائمة بمسارات الحقول مفصولة بفواصل. راجِع هذه المستندات التفصيلية حول كيفية إنشاء مسارات الحقول.

على سبيل المثال، باستخدام هذه الطريقة:

  • كمامة الحقل لجميع الحقول المتاحة (للفحص اليدوي): X-Goog-FieldMask: *
  • قناع الحقل لمدد المسارات والمسافات وحالة العنصر والحالة ومؤشرات العناصر (مثال على إعداد الإنتاج): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

من الضروري تضمين status في قناع الحقل، وإلا ستظهر جميع الرسائل على ما يرام. لا تنصح Google باستخدام قناع حقل الردّ بحرف البدل (*) للسبب التالي:

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

طلب HTTP

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
الحقول
origins[]

object (RouteMatrixOrigin)

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

  • يجب ألا يزيد مجموع عدد المصادر مع عدد الوجهات المحدّدة على أنّها placeId أو address عن 50.
  • يجب ألا يزيد ناتج عدد المصادر × عدد الوجهات عن 625 في أي حالة.
  • يجب ألا يزيد ناتج عدد المصادر × عدد الوجهات عن 100 في حال ضبط إعداد التوجيه المفضّل على TRAFFIC_AWARE_OPTIMAL.
  • يجب ألا يزيد ناتج عدد المصادر × عدد الوجهات عن 100 في حال ضبط travelMode على TRANSIT.
destinations[]

object (RouteMatrixDestination)

مطلوب. مصفوفة للوجهات التي تحدد أعمدة مصفوفة الاستجابة.
travelMode

enum (RouteTravelMode)

اختياريّ. تحدّد هذه السمة وسيلة النقل.
routingPreference

enum (RoutingPreference)

اختياريّ. لتحديد كيفية حساب المسار. يحاول الخادم استخدام تفضيل التوجيه المحدد لاحتساب المسار. إذا أدى تفضيل التوجيه إلى خطأ أو وقت استجابة طويل للغاية، سيتم عرض خطأ. لا يمكنك تحديد هذا الخيار إلا إذا كانت قيمة travelMode هي DRIVE أو TWO_WHEELER، وإلّا يتعذّر تنفيذ الطلب.
departureTime

string (Timestamp format)

اختياريّ. وقت المغادرة إذا لم يتم ضبط هذه القيمة، سيتم ضبط هذه القيمة تلقائيًا على الوقت الذي قدّمت فيه الطلب. ملاحظة: لا يمكنك تحديد departureTime في الماضي إلا عند ضبط RouteTravelMode على TRANSIT.

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
arrivalTime

string (Timestamp format)

اختياريّ. وقت الوصول ملاحظة: لا يمكن ضبط هذا الإعداد إلا عند ضبط RouteTravelMode على TRANSIT. يمكنك تحديد إما departureTime أو arrivalTime، ولكن ليس كليهما.

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".
languageCode

string

اختياريّ. رمز اللغة BCP-47، مثل en-US أو "sr-Latn". للمزيد من المعلومات، يُرجى الاطّلاع على معرّف لغة يونيكود. يمكنك الانتقال إلى قسم دعم اللغات للاطّلاع على قائمة باللغات المتوافقة. في حال عدم تقديم هذه القيمة، يتم استنتاج لغة العرض من الموقع الجغرافي للأصل الأول.
regionCode

string

اختياريّ. تمثّل هذه السمة رمز المنطقة، ويتم تحديده على أنّه قيمة مؤلفة من حرفَين ("نطاق المستوى الأعلى") ccTLD. لمزيد من المعلومات، راجِع نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد.
units

enum (Units)

اختياريّ. تحدّد هذه السمة وحدات القياس لحقول العرض.
extraComputations[]

enum (ExtraComputation)

اختياريّ. قائمة بعمليات الحوسبة الإضافية التي يمكن استخدامها لإكمال الطلب ملاحظة: قد تعرض عمليات الحوسبة الإضافية هذه حقولاً إضافية في الردّ. يجب أيضًا تحديد هذه الحقول الإضافية في قناع الحقل ليتم عرضها في الردّ.
trafficModel

enum (TrafficModel)

اختياريّ. تحدد الافتراضات التي يجب استخدامها عند حساب الوقت المستغرق في حركة المرور. يؤثر هذا الإعداد في القيمة التي يتم عرضها في حقل المدة في RouteMatrixElement، والتي تحتوي على الوقت المتوقّع لعدد الزيارات استنادًا إلى المتوسّطات السابقة. RoutingPreference إلى TRAFFIC_AWARE_OPTIMAL ومن RouteTravelMode إلى DRIVE. ويتم ضبط القيمة تلقائيًا على BEST_GUESS إذا تم طلب الزيارات ولم يتم تحديد TrafficModel.
transitPreferences

object (TransitPreferences)

اختياريّ. تحدّد هذه السياسة الإعدادات المفضّلة التي تؤثر في المسار المعروض لمسارات TRANSIT. ملاحظة: لا يمكنك تحديد transitPreferences إلا عند ضبط "RouteTravelMode" على "TRANSIT".

نص الاستجابة

يحتوي على معلومات مسار محسوبة لزوج المصدر/الوجهة في واجهة برمجة التطبيقات v2.computeRouteMatrix. يمكن بث هذا النموذج الأولي إلى العميل.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
الحقول
status

object (Status)

رمز حالة خطأ لهذا العنصر.
condition

enum (RouteMatrixElementCondition)

يشير إلى ما إذا كان قد تم العثور على المسار أم لا. مستقلة عن الحالة.
distanceMeters

integer

مسافة السفر للمسار، بالأمتار.
duration

string (Duration format)

طول الفترة الزمنية اللازمة للتنقل في المسار. في حال ضبط routingPreference على TRAFFIC_UNAWARE، ستكون هذه القيمة هي نفسها staticDuration. إذا تم ضبط routingPreference على TRAFFIC_AWARE أو TRAFFIC_AWARE_OPTIMAL، سيتم احتساب هذه القيمة مع مراعاة أحوال حركة المرور.

مدة بالثواني مكونة من تسعة أرقام كسور كحد أقصى وتنتهي بالأرقام "s" مثال: "3.5s"
staticDuration

string (Duration format)

مدة التنقّل خلال المسار بدون مراعاة أحوال حركة المرور.

مدة بالثواني مكونة من تسعة أرقام كسور كحد أقصى وتنتهي بالأرقام "s" مثال: "3.5s"
travelAdvisory

object (RouteTravelAdvisory)

معلومات إضافية حول المسار على سبيل المثال: معلومات عن القيود المفروضة على رسوم العبور ومعلومات عن رسوم العبور
fallbackInfo

object (FallbackInfo)

في بعض الحالات عندما لا يتمكن الخادم من حساب المسار باستخدام التفضيلات المحددة لهذا الزوج من نقطة الانطلاق/الوجهة، قد يعود إلى استخدام وضع حساب مختلف. عند استخدام الوضع الاحتياطي، يحتوي هذا الحقل على معلومات تفصيلية حول الاستجابة الاحتياطية. وبخلاف ذلك، يتم إلغاء ضبط هذا الحقل.
localizedValues

object (LocalizedValues)

تمثيلات نصية لخصائص RouteMatrixElement.
originIndex

integer

فهرس مبني على صفر للمنشأ في الطلب.
destinationIndex

integer

فهرس يستند إلى صفر للوجهة في الطلب.

RouteMatrixOrigin

مصدر واحد لـ ComputeRouteMatrixRequest

تمثيل JSON 
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
الحقول
waypoint

object (Waypoint)

مطلوب. نقطة طريق نقطة الانطلاق
routeModifiers

object (RouteModifiers)

اختياريّ. إعدادات تعديل كل مسار يتخذ هذا باعتباره المصدر

RouteMatrixDestination

وجهة واحدة لـ ComputeRouteMatrixRequest

تمثيل JSON 
{
  "waypoint": {
    object (Waypoint)
  }
}
الحقول
waypoint

object (Waypoint)

مطلوب. نقطة طريق الوجهة

ExtraComputation

إجراء عمليات حسابية إضافية أثناء إكمال الطلب

عمليات التعداد
EXTRA_COMPUTATION_UNSPECIFIED غير مستخدَم سيتعذّر تنفيذ الطلبات التي تحتوي على هذه القيمة.
TOLLS تشير هذه السمة إلى معلومات حول رسوم المرور لعناصر المصفوفة.

RouteMatrixElementCondition

حالة المسار الذي يتم إرجاعه.

عمليات التعداد
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED لا تُستخدَم إلا عندما يكون status للعنصر غير مناسب.
ROUTE_EXISTS تم العثور على مسار وملء المعلومات المقابلة للعنصر.
ROUTE_NOT_FOUND تعذَّر العثور على مسار. ولن يتم ملء الحقول التي تحتوي على معلومات المسار، مثل distanceMeters أو duration.

LocalizedValues

تمثيلات نصية لسمات معيّنة

تمثيل JSON 
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
الحقول
distance

object (LocalizedText)

مسافة السفر ممثلة في شكل نصي.
duration

object (LocalizedText)

المدة ممثلة في شكل نصي مع أخذ ظروف الزيارات في الاعتبار. ملاحظة: في حال عدم طلب معلومات الزيارات، تكون هذه القيمة هي القيمة نفسها لـ staticDuration.
staticDuration

object (LocalizedText)

يتم تمثيل المدة في شكل نصي بدون أخذ ظروف الزيارات في الاعتبار.
transitFare

object (LocalizedText)

يتم عرض سعر النقل العام في شكل نصي.