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

استخدِم 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.