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 "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"
arrivalTime

string (Timestamp format)

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

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

string

اختياريّ. رمز اللغة BCP-47، مثل en-US أو sr-Latn لمزيد من المعلومات، يُرجى الاطّلاع على معرِّف لغة Unicode. راجِع دعم اللغة للاطّلاع على قائمة اللغات المتاحة. في حال عدم توفير هذه القيمة، يتم استنتاج لغة العرض من الموقع الجغرافي الأصلي.
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)

يتم تمثيل تعرفة النقل العام في شكل نصي.