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://routespreferred.googleapis.com/v1alpha:computeRouteMatrix

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string
}
الحقول
origins[]

object (RouteMatrixOrigin)

مطلوب. مصفوفة من الأصول، تحدّد صفوف مصفوفة الاستجابة. تنطبق عدة قيود على عدد القيم الفريدة للنقاط الجغرافية التي تمثل نقاط الانطلاق والوجهة:

  • يجب ألا يزيد عدد العناصر (المصادر × الوجهات) عن 625 في أي حالة.
  • يجب ألا يكون عدد العناصر (المصادر × الوجهات) أكبر من 100 في حال ضبط التوجيه المفضّل على TRAFFIC_AWARE_OPTIMAL.
  • يجب ألا يزيد عدد نقاط التوقف (المواقع الجغرافية للنقاط المرجعية + الوجهات) المحدّدة على أنّها placeId عن 50.
destinations[]

object (RouteMatrixDestination)

مطلوب. صفيف الوجهات الذي يحدّد أعمدة مصفوفة الاستجابة
travelMode

enum (RouteTravelMode)

اختياريّ. تحدّد هذه السمة وسيلة النقل.
routingPreference

enum (RoutingPreference)

اختياريّ. تُحدِّد كيفية احتساب المسار. يحاول الخادم استخدام تفضيل التوجيه المحدد لاحتساب المسار. إذا أدّى خيار التوجيه المفضّل إلى حدوث خطأ أو وقت استجابة طويل جدًا، يتم عرض خطأ. لا يمكنك تحديد هذا الخيار إلا عندما يكون travelMode هو DRIVE أو TWO_WHEELER، وإلا سيتعذّر إكمال الطلب.
departureTime

string (Timestamp format)

اختياريّ. وقت المغادرة وإذا لم تضبط هذه القيمة، سيتم ضبط هذه القيمة تلقائيًا على الوقت الذي قدّمت فيه الطلب. وفي حال ضبط هذه القيمة على وقت قد حدث بالفعل، سيتعذّر الطلب.

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

نص الاستجابة

في حال النجاح، يحتوي نص الاستجابة على سلسلة من RouteMatrixElement أمثلة.

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/maps-platform.routespreferred

لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على بروتوكول OAuth 2.0.