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

استخدِم Routes API لاحتساب المسافة ومدة المسار لنقاط منشأ ووجهات متعددة من خلال استدعاء الأسلوب computeRouteMatrix (REST) أو الأسلوب المخصّص للبث ComputeRouteMatrix (gRPC).

استنادًا إلى قائمة بالمصادر والوجهات، تُحتسب الطريقة المسافة ومدة المسار الذي يبدأ من كل مصدر وينتهي في كل وجهة.

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

يمكنك أيضًا احتساب مصفوفة مسارات على وسائل النقل العام. للحصول على مثال، يُرجى الاطّلاع على الحصول على مصفوفة مسارات للنقل العام.

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

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

• عدد العناصر: لا يمكن أن يتجاوز 625 للمسارات التي ليست مسارات TRANSIT.

• في حال تحديد TRANSIT مسار، لا يمكن أن يتجاوز عدد العناصر 100.

• في حال تحديد TRAFFIC_AWARE_OPTIMAL، لا يمكن أن يتجاوز عدد العناصر 100 عنصر. لمزيد من المعلومات عن TRAFFIC_AWARE_OPTIMAL، اطّلِع على تحديد كيفية تضمين بيانات الزيارات وما إذا كان سيتم تضمينها.

• في حال تحديد نقاط الانطلاق أو الوجهة باستخدام عنوان أو رقم تعريف مكان، يمكنك تحديد ما يصل إلى 50 نقطة بهذه الطريقة.

أخطاء الاستجابة

من ميزات طرق Compute Route Matrix أنّه يمكن عرض الأخطاء إما للردّ بأكمله أو لعناصر الردّ الفردية. على سبيل المثال، يحتوي الردّ بأكمله على خطأ إذا كان الطلب بتنسيق غير صحيح (على سبيل المثال، إذا لم يكن يتضمّن أي مصادر).

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

نتائج بث gRPC

تتلقّى طريقة ComputeRouteMatrix gRPC قائمة بالمواقع الجغرافية للنقاط المنشأة والوجهات، وتُعيد بثًا يحتوي على معلومات عن المسار لكل مجموعة من المواقع الجغرافية للنقاط المنشأة والوجهات. وبما أنّ النتائج يتم عرضها في شكل بث، ليس عليك الانتظار إلى أن يتم احتساب جميع مجموعات المسارات المحتملة قبل أن تتمكّن من بدء معالجة النتائج.

ملاحظة: لا تتيح واجهة برمجة التطبيقات REST نتائج البث.

لا يمكن ضمان عرض العناصر التي يعرضها البث بأي ترتيب. لذلك، يحتوي كل عنصر ردّ على origin_index و destination_index. بالنسبة إلى مصادر الخطوط ووجهاتها المحدّدة في الطلب، يكون مصدر المسار مكافئًا لـ origins[origin_index] لعنصر معيّن وتكون وجهة المسار مكافئة لـ destinations[destination_index]. يتمّ فهرسة هذه المصفوفات من الصفر. من المهم تخزين طلبات قائمة المنشأ والوجهة.

أمثلة على احتساب مصفوفة المسارات

استخدِم الطريقة computeRouteMatrix في طلب HTTP لاحتساب مصفوفة مسار.

مثال على HTTP

يعرض المثال التالي طلب HTTP computeRouteMatrix. في هذا المثال، عليك إجراء ما يلي:

• حدِّد صفيفًا من نقطتَي بداية ووجهة. تحسب الطريقة مسارًا من كل نقطة انطلاق إلى كل وجهة، لذا يحتوي الردّ على أربعة مسارات.

  في المصفوفة، يكون العنصر الأول في الفهرس 0، والثاني في الفهرس 1، وهكذا.

• أدرِج قناع حقل استجابة لتحديد حقول الاستجابة (REST) أو ComputeRoutesResponse (gRPC) التي تريد عرضها. في هذا المثال، يمكنك ضبط الطلب لعرض originIndex وdestinationIndex وduration وdistanceMeters وstatus وcondition لكل مسار. لمزيد من المعلومات، يُرجى الاطّلاع على اختيار الحقول التي سيتم عرضها.

curl -X POST -d '{
  "origins": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420761,
            "longitude": -122.081356
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.403184,
            "longitude": -122.097371
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    }
  ],
  "destinations": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420999,
            "longitude": -122.086894
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.383047,
            "longitude": -122.044651
          }
        }
      }
    }
  ],
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status,condition' \
'https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix'

يحتوي الردّ على المسارات الأربعة المحتملة لتركيبة جميع نقاط الطريق للمصدر والوجهة.

ملاحظة: للحصول على وصف تفصيلي للردّ، اطّلِع على فهم ردّ مصفوفة مسار المعالجة.

حدِّد كل مسار في الاستجابة باستخدام حقلَي الاستجابة originIndex و destinationIndex. على سبيل المثال، يتوافق القيمة 1 لعنصر originIndex في الردّ مع مسار يتم احتسابه من نقطة الطريق في الفهرس 1 من صفيف origins في الطلب.

[
    {
        "originIndex": 0,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 822,
        "duration": "160s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 2919,
        "duration": "361s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 5598,
        "duration": "402s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 0,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 7259,
        "duration": "712s",
        "condition": "ROUTE_EXISTS"
    }
]

أمثلة على gRPC

على سبيل المثال، طلبات gRPC، يمكنك الاطّلاع على الأمثلة في مثال على طلب gRPC. يُطلِق مثال Java في تلك الصفحة كلًّا من Compute Routes و Compute Route Matrix.