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,
  "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 ("نطاق المستوى الأعلى") الذي يتكوّن من حرفين. لمزيد من المعلومات، يُرجى الاطّلاع على نطاقات المستوى الأعلى لرمز البلد.
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)

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