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.

يجب أن يكون طابعًا زمنيًا بالتنسيق 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

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

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