الحصول على مصفوفة مسار

مصفوفة المسارات هي مصفوفة ثنائية الأبعاد تتضمّن معلومات المسارات، حيث تتوافق الصفوف مع نقاط البداية والأعمدة مع الوجهات. عند توفّر قائمة بنقاط الانطلاق والوجهات، تحسب فئة "مصفوفة المسارات" المسافة ومدة المسار بدءًا من كل نقطة انطلاق وانتهاءً بكل وجهة. استخدِم فئة Route Matrix لحساب مسافة ومدة مسار لعدّة نقاط بداية ووجهات.

الحدود القصوى المسموح بها للطلبات

تفرض الطريقة RouteMatrix.computeRouteMatrix() حدود الطلبات التالية لنقاط الطريق باستخدام مثيلات العناوين أو الأماكن، وللعناصر. العناصر هي المسارات بين كل نقطة انطلاق ووجهة في مصفوفة المسارات، وبالتالي فإنّ عدد العناصر هو عدد نقاط الانطلاق مضروبًا في عدد الوجهات. على سبيل المثال، إذا كان لديك 10 مصادر و10 وجهات، سيكون لديك 100 عنصر:

  • لا يمكن أن يتجاوز عدد العناصر 625 للطرق التي ليست طرقًا من النوع TRANSIT.
  • في حال تحديد TRANSIT مسار، يجب ألا يتجاوز عدد العناصر 100.
  • في حال تحديد TRAFFIC_AWARE_OPTIMAL، يجب ألا يتجاوز عدد العناصر 100.
  • إذا حدّدت المصادر أو الوجهات باستخدام العناوين أو مثيلات المكان، يمكنك تحديد ما يصل إلى 50 إجماليًا بهذه الطريقة.

مثال على طلب مصفوفة الطرق

يوضّح المثال التالي ComputeRouteMatrixRequest. يُجري هذا المثال ما يلي:

  • تعرض هذه السمة كيفية تحديد مصفوفة من نقطتَي طريق للمصدر ونقطتَي طريق للوجهة. تحسب الطريقة مسارًا من كل نقطة انطلاق إلى كل وجهة، لذا يحتوي الرد على أربعة مسارات.
    في المصفوفة، يكون العنصر الأول في الفهرس 0، والعنصر الثاني في الفهرس 1، وهكذا.
  • حدِّد الحقول المطلوب عرضها. في هذا المثال، اضبط الطلب لعرض durationMillis وdistanceMeters وcondition لكل مسار. 
const request = {
  origins: [origin1, origin2],
  destinations: [destinationA, destinationB],
  travelMode: google.maps.TravelMode.DRIVING,
  units: google.maps.UnitSystem.METRIC,
  fields: ['durationMillis', 'distanceMeters', 'condition'], 
};

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

"matrix": {
  "rows": [
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 202587,
          "durationMillis": 10040000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 252734,
          "durationMillis": 12240000
        }
      ]
    },
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 166135,
          "durationMillis": 6596000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 216282,
          "durationMillis": 8797000
        }
      ]
    }
  ]
}

حدِّد كل مسار في النتيجة باستخدام فهرسَي نقطة البداية ونقطة النهاية للعثور على RouteMatrixItem المقابل في المصفوفة الثنائية الأبعاد. على سبيل المثال، سيكون RouteMatrixItem الذي يصف المسار المحسوب من نقطة الانطلاق في الفهرس 1 والوجهة 0 في الطلب في العنصر الثاني من مصفوفة RouteMatrix.rows والعنصر الأول من مصفوفة RouteMatrixRow.items.

يوضّح مقتطف الرمز التالي كيفية تحديد RouteMatrixItem للعثور على المسار لمصدر ووجهة محدّدين: 

// Find the route for origin 'x' and destination 'y'.
const {matrix} = await RouteMatrix.computeRouteMatrix(request);
const myRouteMatrixItem = matrix.rows[x].items[y];

اختيار الحقول المطلوب إرجاعها

عند طلب مصفوفة طرق، يجب استخدام قناع حقل لتحديد المعلومات التي يجب أن تعرضها الاستجابة.

يضمن استخدام قناع الحقل أيضًا عدم طلب بيانات غير ضرورية، ما يساعد بدوره في تقليل وقت استجابة الطلب وتجنُّب عرض معلومات لا يحتاج إليها نظامك.

حدِّد قائمة الحقول التي تحتاج إليها من خلال ضبط السمة ComputeRoutesMatrixRequest.fields، كما هو موضّح في المقتطف التالي: 

fields: ['durationMillis', 'distanceMeters', 'condition'],

تحديد حقول الأقنعة التي يجب استخدامها

في ما يلي كيفية تحديد الحقول التي تريد استخدامها وإنشاء أقنعة الحقول لها:

  1. اطلب جميع الحقول باستخدام قناع الحقل ['*'].
  2. اطّلِع على التسلسل الهرمي للحقول في الفئة RouteMatrixItem للحقول التي تريدها.

  3. أنشئ أقنعة الحقول باستخدام التسلسل الهرمي للحقول المعروضة في الخطوة السابقة، وذلك باتّباع التنسيق التالي:

    topLevelField[.secondLevelField][.thirdLevelField][...]

على سبيل المثال، بالنسبة إلى RouteMatrixItem:

  "travelAdvisory": {
    "fuelConsumptionMicroliters": 0,
    "tollInfo": {
      "estimatedPrices": [
        {
          "currencyCode": "USD",
          "units": 4,
          "nanos": 400000000
        }
      ]
    }
  },

إذا كنت تريد عرض الحقل tollInfo فقط للسمة RouteMatrixItem، سيكون قناع الحقل على النحو التالي:

fields: ['travelAdvisory.tollInfo']

إذا كنت تريد بدلاً من ذلك طلب استهلاك الوقود المقدَّر، سيكون قناع الحقل على النحو التالي:

fields: ['travelAdvisory.fuelConsumptionMicroliters']

إذا أردت طلب كليهما، سيكون قناع الحقل على النحو التالي:

fields: ['travelAdvisory.fuelConsumptionMicroliters', 'travelAdvisory.tollInfo']

وإذا أردت طلب المجموعة الكاملة من إرشادات السفر، سيكون قناع الحقل على النحو التالي:

fields: ['travelAdvisory']