- طلب 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) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
arrivalTime |
اختياريّ. وقت الوصول ملاحظة: لا يمكن ضبط هذا الإعداد إلا عند ضبط طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: |
languageCode |
اختياريّ. رمز اللغة BCP-47، مثل en-US أو "sr-Latn". للمزيد من المعلومات، يُرجى الاطّلاع على معرّف لغة يونيكود. يمكنك الانتقال إلى قسم دعم اللغات للاطّلاع على قائمة باللغات المتوافقة. في حال عدم تقديم هذه القيمة، يتم استنتاج لغة العرض من الموقع الجغرافي للأصل الأول. |
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 |
يتم عرض سعر النقل العام في شكل نصي. |