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 إذا تم ضبط routingPreference على 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.

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر غير "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
arrivalTime

string (Timestamp format)

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

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر غير "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
languageCode

string

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

string

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

enum (Units)

اختياريّ. تُستخدَم لتحديد وحدات القياس لحقول العرض.
extraComputations[]

enum (ExtraComputation)

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

enum (TrafficModel)

اختياريّ. تُحدِّد الافتراضات التي يجب استخدامها عند احتساب الوقت الذي يقضيه المستخدم في حركة المرور. يؤثر هذا الإعداد في القيمة المعروضة في حقل المدة في RouteMatrixElement الذي يحتوي على الوقت المتوقّع في عدد الزيارات استنادًا إلى القيم المتوسطة السابقة. لا يتوفّر TrafficModel إلا للطلبات التي تم ضبط 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

وجهة واحدة لطلب ComputeRouteMatrix

تمثيل 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)

تعرفة النقل العام معروضة في شكل نص