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

وجهة واحدة لطلب 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)

تمثّل هذه السمة أجرة النقل العام في شكل نص.