- طلب HTTP
- نص الطلب
- نص الاستجابة
- RouteMatrixOrigin
- RouteMatrixDestination
- ExtraComputation
- RouteMatrixElementCondition
- LocalizedValues
يأخذ قائمة بالمصادر والوجهات ويعرض مجموعة بث تحتوي على معلومات المسار لكل مجموعة من نقطة الانطلاق والوجهة.
ملاحظة: تتطلّب هذه الطريقة تحديد قناع حقل الاستجابة في الإدخال. يمكنك توفير قناع حقل الاستجابة باستخدام مَعلمة عنوان 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 ( |
الحقول | |
---|---|
origins[] |
مطلوبة. مصفوفة الأصول التي تحدد صفوف مصفوفة الاستجابة. تنطبق العديد من القيود على عدد القيم الفريدة للسمة على المصادر والوجهات:
|
destinations[] |
مطلوبة. مصفوفة الوجهات التي تحدد أعمدة مصفوفة الاستجابة. |
travelMode |
اختياريّ. تحدِّد هذه السمة وسيلة النقل. |
routingPreference |
اختياريّ. لتحديد كيفية حساب المسار. يحاول الخادم استخدام تفضيل التوجيه المحدد لحساب المسار. إذا أدى تفضيل التوجيه إلى حدوث خطأ أو وقت استجابة طويل جدًا، سيتم عرض خطأ. لا يمكنك تحديد هذا الخيار إلا إذا كانت قيمة |
departureTime |
اختياريّ. وقت المغادرة وفي حال عدم ضبط هذه القيمة، سيتم ضبط هذه القيمة تلقائيًا على الوقت الذي قدّمت الطلب فيه. ملاحظة: يمكنك فقط تحديد طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
arrivalTime |
اختياريّ. وقت الوصول ملاحظة: لا يمكن الضبط إلا عند ضبط طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
languageCode |
اختياريّ. رمز اللغة BCP-47، مثل en-US أو sr-Latn لمزيد من المعلومات، يُرجى الاطّلاع على معرِّف لغة Unicode. راجِع دعم اللغة للاطّلاع على قائمة اللغات المتاحة. في حال عدم توفير هذه القيمة، يتم استنتاج لغة العرض من الموقع الجغرافي الأصلي. |
regionCode |
اختياريّ. تشير هذه السمة إلى رمز المنطقة، ويتم تحديده على أنّه نطاق مستوى أعلى يتم ترميزه حسب البلد (ccTLD) مكوَّن من حرفين ("نطاق المستوى الأعلى"). لمزيد من المعلومات، يُرجى الاطّلاع على نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد. |
units |
اختياريّ. تحدِّد وحدات القياس لحقول العرض. |
extraComputations[] |
اختياريّ. قائمة بإجراءات العمليات الحسابية الإضافية التي يمكن استخدامها لإكمال الطلب ملاحظة: قد تؤدي هذه العمليات الحسابية الإضافية إلى عرض حقول إضافية في الاستجابة. يجب أيضًا تحديد هذه الحقول الإضافية في قناع الحقل لعرضها في الاستجابة. |
trafficModel |
اختياريّ. تحدد الافتراضات المراد استخدامها عند حساب الوقت في حركة المرور. يؤثر هذا الإعداد في القيمة المعروضة في حقل المدة في |
transitPreferences |
اختياريّ. يحدّد الإعداد الإعدادات المفضّلة التي تؤثر في المسار الذي يتم عرضه لمسارات |
نص الاستجابة
يحتوي على معلومات المسار المحسوبة لزوج المصدر/الوجهة في واجهة برمجة التطبيقات v2.computeRouteMatrix. يمكن بث هذا النموذج الأولي إلى العميل.
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
تمثيل JSON |
---|
{ "status": { object ( |
الحقول | |
---|---|
status |
رمز حالة خطأ لهذا العنصر. |
condition |
يشير إلى ما إذا كان يتم العثور على المسار أم لا. مستقلة عن الحالة. |
distanceMeters |
مسافة السفر على المسار بالمتر. |
duration |
المدة الزمنية اللازمة للتنقل في المسار. وإذا تم ضبط قيمة مدة بالثواني يصل عددها إلى تسعة أرقام كسرية وتنتهي بـ " |
staticDuration |
مدة السفر عبر المسار دون وضع أحوال حركة المرور في الاعتبار. مدة بالثواني يصل عددها إلى تسعة أرقام كسرية وتنتهي بـ " |
travelAdvisory |
معلومات إضافية حول المسار. على سبيل المثال: معلومات القيود ومعلومات العبور |
fallbackInfo |
في بعض الحالات التي لا يتمكن فيها الخادم من احتساب المسار باستخدام التفضيلات المحددة لزوج المصدر/الوجهة المعيّن، قد يعود إلى استخدام وضع حساب مختلف. عند استخدام الوضع الاحتياطي، يحتوي هذا الحقل على معلومات تفصيلية عن الاستجابة الاحتياطية. وبخلاف ذلك، لن يتم ضبط هذا الحقل. |
localizedValues |
تمثيلات نصية لسمات |
originIndex |
فهرس يستند إلى الصفر للأصل في الطلب. |
destinationIndex |
فهرس الوجهة الصفري للوجهة في الطلب. |
RouteMatrixOrigin
مصدر واحد لـ ComputeRouteMatrixRequest
تمثيل JSON |
---|
{ "waypoint": { object ( |
الحقول | |
---|---|
waypoint |
مطلوبة. نقطة الانطلاق |
routeModifiers |
اختياريّ. معدِّلات لكل مسار يأخذ هذا المسار على أنه نقطة الانطلاق |
RouteMatrixDestination
وجهة واحدة لـ ComputeRouteMatrixRequest
تمثيل JSON |
---|
{
"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 ( |
الحقول | |
---|---|
distance |
يتم تمثيل مسافة السفر في شكل نصي. |
duration |
يتم تمثيل المدة في نموذج نصي مع مراعاة ظروف الزيارات. ملاحظة: إذا لم يتم طلب معلومات حركة المرور، ستكون هذه القيمة هي نفس قيمة staticDuration. |
staticDuration |
يتم تمثيل المدة في شكل نصي بدون وضع ظروف حركة المرور في الاعتبار. |
transitFare |
يتم تمثيل تعرفة النقل العام في شكل نصي. |