قائمة المَعلمات

تحتوي الصفحة التالية على جداول المَعلمات مرتّبة أبجديًا لمكوّنات طريقة optimizeTours في Route Optimization API التالية:

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

نص الطلب

بنية البيانات لنص الطلب

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

  • OptimizeToursRequest: كائن الطلب ذو المستوى الأعلى الذي يحتوي على النموذج ومعلَمات الحلّ.
    • ShipmentModel: بنية البيانات الأساسية التي تحتوي على الشحنات والمركبات والقيود العالمية.
      • Shipment: مهمة تتضمّن عمليات استلام وتوصيل
        • VisitRequest: تمثّل هذه السمة الموقع الجغرافي والقيود المتعلقة باستلام الطلب أو تسليمه.
      • Vehicle: مركبة متاحة لتنفيذ عمليات الشحن
أحد الوالدين المَعلمة نوع مكان الإقامة الوصف
OptimizeToursRequest allowLargeDeadlineDespiteInterruptionRisk قيمة منطقية (true/false) إذا كانت القيمة true، تتم معالجة الطلب حتى إذا تم ضبط المهلة على قيمة كبيرة (أكثر من 30 دقيقة) قد تؤدي إلى حدوث انقطاعات محتملة في الخادم.
considerRoadTraffic قيمة منطقية (true/false) إذا كانت true، تستخدم بيانات حركة المرور لتحديد المسار. إذا كانت القيمة false، يتم استخدام سرعات شبكة الطرق فقط.
geodesicMetersPerSecond الرقم عندما تكون قيمة useGeodesicDistances صحيحة، يتم استخدام هذه السرعة لاحتساب أوقات السفر.
injectedFirstSolutionRoutes[] مصفوفة من العناصر (ShipmentRoute) المسارات من حلّ سابق لبدء التحسين منها
injectedSolutionConstraint الكائن (InjectedSolutionConstraint) يفرض قيودًا على الحلّ ليكون مشابهًا للطرق الحالية، ويحدّد الخصائص التي يجب الحفاظ عليها والخصائص التي يمكن تخفيفها.
interpretInjectedSolutionsUsingLabels قيمة منطقية (true/false) إذا كانت القيمة true، تتم مطابقة الشحنات أو المركبات في المسارات التي تم إدخالها حسب label بدلاً من فهرس المصفوفة.
label سلسلة تصنيف اختياري لتحديد الطلب، ويتم عرضه في الردّ.
maxValidationErrors عدد صحيح تحدّد هذه السمة الحد الأقصى لعدد أخطاء التحقّق التي سيتم عرضها. في حال عدم تحديد حد أقصى، يتم تطبيق حد تلقائي.
model الكائن (ShipmentModel) الحقل مطلوب. مجموعة المركبات والشحنات المطلوب تحسينها.
populatePolylines قيمة منطقية (true/false) في حال true، يتم عرض خطوط متعدّدة الأضلاع مشفّرة للمسارات.
populateTransitionPolylines قيمة منطقية (true/false) إذا كانت القيمة true، تعرض هذه السمة خطوطًا متعددة مبرمَجة للانتقالات الفردية بين الزيارات.
refreshDetailsRoutes[] مصفوفة من العناصر (ShipmentRoute) قائمة بالمسارات التي سيتم إعادة تحميلها. تعيد هذه الطريقة احتساب الخطوط المتعددة الأضلاع والمدد والمسافات للمسارات الحالية بدون تعديل ترتيب الزيارات.
searchMode enum (SearchMode) RETURN_FAST (نتائج سريعة) أو CONSUME_ALL_AVAILABLE_TIME (أفضل جودة ضمن المهلة المحدّدة)
solvingMode enum (SolvingMode) DEFAULT_SOLVE (القيمة التلقائية) أو VALIDATE_ONLY للتحقّق من صحة النموذج بدون حلّه
timeout المدة المدة القصوى التي يجب أن يعمل خلالها برنامج الحل (مثلاً، "30s" و"300s").
useGeodesicDistances قيمة منطقية (true/false) في حال true، يتم احتساب مسافات الرحلات ومدتها باستخدام المسافات الجيوديسية (الخط المستقيم) والسرعة geodesicMetersPerSecond.
ShipmentModel
(جزء من OptimizeToursRequest)
durationDistanceMatrices[] مصفوفة من العناصر (DurationDistanceMatrix) تحدّد هذه السمة مصفوفات المدة والمسافة المخصّصة المستخدَمة للتوجيه بين المواقع الجغرافية.
durationDistanceMatrixDstTags[] مصفوفة سلاسل علامات تحدّد وجهات (أعمدة) مصفوفات المدة والمسافة المخصّصة
durationDistanceMatrixSrcTags[] مصفوفة سلاسل علامات تحدّد المصادر (الصفوف) لمصفوفات المدة والمسافة المخصّصة.
globalDurationCostPerHour الرقم التكلفة لكل ساعة من الفترة الزمنية العالمية للمسار، من بداية تشغيل المركبة في أقرب وقت إلى نهاية تشغيلها في أبعد وقت
globalEndTime الطابع الزمني تمثّل هذه السمة آخر وقت انتهاء لأي حدث في النموذج.
globalStartTime الطابع الزمني تمثّل هذه السمة أقرب وقت بدء لأي حدث في النموذج.
maxActiveVehicles عدد صحيح الحدّ الأقصى لعدد المركبات المسموح بأن تكون نشطة في الحلّ
precedenceRules[] مصفوفة من العناصر (PrecedenceRule) قواعد تحدّد قيود الترتيب بين شحنات معيّنة
shipments[] مصفوفة من العناصر (Shipment) قائمة الشحنات المطلوب تقديم الخدمة لها
shipmentTypeIncompatibilities[] مصفوفة من العناصر (ShipmentTypeIncompatibility) قواعد تمنع نقل شحنات من أنواع معيّنة في المركبة نفسها
shipmentTypeRequirements[] مصفوفة من العناصر (ShipmentTypeRequirement) قواعد تتطلّب أن يتم نقل شحنات من أنواع معيّنة بالمركبة نفسها
transitionAttributes[] مصفوفة من العناصر (TransitionAttributes) تحدّد هذه السمة التكاليف الإضافية والتأخيرات وحدود المسافة للانتقالات بين الزيارات التي تتضمّن علامات محدّدة.
vehicles[] مصفوفة من العناصر (Vehicle) قائمة المركبات المتاحة لتنفيذ عمليات الشحن
Shipment
(جزء من ShipmentModel)
allowedVehicleIndices[] مصفوفة أعداد صحيحة فهارس المركبات المسموح لها بتنفيذ هذه الشحنة
costsPerVehicle[] خريطة (المفتاح: عدد صحيح، القيمة: رقم) تمثّل هذه السمة التكاليف الإضافية التي يتم تكبّدها إذا كانت مركبة معيّنة تقدّم خدمة الشحن هذه.
costsPerVehicleIndices[] مصفوفة أعداد صحيحة فهارس المركبات التي تنطبق عليها قيم costsPerVehicle
deliveries[] مصفوفة من العناصر (VisitRequest) بدائل لتسليم الشحنة
ignore قيمة منطقية (true/false) إذا كانت القيمة true، يتم تجاهل الشحنة وعدم استخدامها في التحسين.
label سلسلة تصنيف يحدّده المستخدم لتحديد الشحنة، ويتم عرضه في الردّ.
loadDemands خريطة (المفتاح: سلسلة، القيمة: Load) تمثّل هذه السمة السعة المطلوبة (مثل الوزن أو الحجم) لنقل هذه الشحنة.
penaltyCost الرقم تمثّل هذه السمة التكلفة في حال عدم توفّر خدمة الشحن. في حال عدم ضبط هذه السمة، تكون الشحنة إلزامية.
pickups[] مصفوفة من العناصر (VisitRequest) بدائل لاستلام الشحنة
pickupToDeliveryAbsoluteDetourLimit المدة الحدّ الأقصى لوقت التحويلة المطلق المسموح به بين الاستلام والتسليم مقارنةً بالمسار المباشر.
pickupToDeliveryRelativeDetourLimit الرقم الحدّ الأقصى المسموح به للانحراف النسبي عن المسار للشحنة (على سبيل المثال، تعني القيمة 2.0 أنّ إجمالي الوقت يمكن أن يكون ضعف مدة الرحلة المباشرة على الأكثر).
pickupToDeliveryTimeLimit المدة الحدّ الأقصى لمدة التوصيل المسموح بها من بداية الاستلام إلى بداية التسليم
shipmentType سلسلة تصنيف النوع المستخدَم لقواعد عدم التوافق والمتطلبات
VisitRequest
(أحد مكونات pickups وdeliveries في Shipment)
arrivalLocation الكائن (LatLng) الموقع الجغرافي للوصول على شكل إحداثيات خط العرض/خط الطول
arrivalWaypoint الكائن (Waypoint) الموقع الجغرافي الذي تصل إليه المركبة لإجراء الزيارة يتم تحديدها من خلال الإحداثيات أو معرّف المكان.
cost الرقم التكلفة التي يتم تكبّدها إذا اختار الحلّال طلب الزيارة المحدّد هذا.
departureLocation الكائن (LatLng) الموقع الجغرافي للمغادرة على شكل إحداثيات خطوط الطول والعرض
departureWaypoint الكائن (Waypoint) الموقع الجغرافي الذي تغادر منه المركبة بعد إكمال الزيارة في حال عدم توفّرها، سيتم افتراض أنّها مماثلة للسمة arrivalWaypoint.
duration المدة مدة الزيارة (وقت الخدمة)، مثلاً المدة التي يستغرقها التحميل أو التفريغ
label سلسلة تصنيف يحدّده المستخدم لطلب الزيارة المحدّد هذا، ويتم عرضه في الردّ.
loadDemands خريطة (المفتاح: سلسلة، القيمة: Load) طلبات تحديد تغيير التحميل في هذه الزيارة (مثلاً، ‫-1 لتسليم حزمة).
tags[] مصفوفة سلاسل العلامات المرتبطة بطلب الزيارة هذا يتم استخدامها لاحتساب مدة السفر بين هذه الزيارة وغيرها باستخدام transitionAttributes.
timeWindows[] مصفوفة من العناصر (TimeWindow) تمثّل هذه السمة نوافذ الوقت المسموح بها للوصول إلى هذا الموقع.
visitTypes[] مصفوفة سلاسل سلاسل تصف نوع الزيارة (مثل "delivery", "installation"). تُستخدَم لتطبيق extraVisitDurationForVisitType من طراز المركبة.
Vehicle
(جزء من ShipmentModel)
breakRule الكائن (BreakRule) تحدّد هذه السمة قواعد الاستراحات (مثل استراحة الغداء الإلزامية).
costPerHour الرقم تمثّل هذه السمة تكلفة الساعة الواحدة من إجمالي مدة المسار.
costPerKilometer الرقم التكلفة لكل كيلومتر تم قطعه
costPerTraveledHour الرقم التكلفة لكل ساعة أثناء تحرّك المركبة
endLocation الكائن (LatLng) تمثّل هذه السمة الموقع الجغرافي النهائي كإحداثيات خطوط الطول والعرض.
endTags[] مصفوفة سلاسل علامات تحدّد حالة المركبة النهائية، وتُستخدم لسمات الانتقال
endTimeWindows[] مصفوفة من العناصر (TimeWindow) فترات زمنية مسموح بها لإنهاء مسار المركبة
endWaypoint الكائن (Waypoint) الموقع الجغرافي النهائي باستخدام نقطة على المسار (الإحداثيات أو رقم تعريف المكان).
extraVisitDurationForVisitType خريطة (المفتاح: سلسلة، القيمة: المدة) تضيف هذه السمة مدة إضافية إلى الزيارات استنادًا إلى visitType.
fixedCost الرقم تكلفة ثابتة يتم تطبيقها في حال استخدام المركبة، بغض النظر عن مسافة المسار أو مدته
ignore قيمة منطقية (true/false) في حال true، يتم تجاهل المركبة وعدم استخدامها في التحسين.
label سلسلة تصنيف يحدّده المستخدم للمركبة، ويتم عرضه في الردّ.
loadLimits خريطة (المفتاح: سلسلة، القيمة: LoadLimit) سعات المركبات (مثل الحد الأقصى للوزن والحد الأقصى للحجم)
routeDistanceLimit الكائن (DistanceLimit) حدّ أقصى ثابت أو مرن لإجمالي مسافة مسار المركبة
routeDurationLimit الكائن (DurationLimit) حدّ أقصى ثابت أو مرن لإجمالي مدة مسار المركبة.
routeModifiers الكائن (RouteModifiers) قيد واحد أو عدة قيود، مثل تجنُّب رسوم العبور أو الطرق السريعة أو العبّارات
startLocation الكائن (LatLng) الموقع الجغرافي لبداية الرحلة كإحداثيات خطوط العرض/الطول
startTags[] مصفوفة سلاسل علامات تحدّد حالة بدء المركبة، وتُستخدَم لسمات الانتقال
startTimeWindows[] مصفوفة من العناصر (TimeWindow) الفترات الزمنية المسموح فيها للمركبة ببدء مسارها
startWaypoint الكائن (Waypoint) الموقع الجغرافي لبدء الرحلة باستخدام نقطة طريق (إحداثيات أو رقم تعريف المكان)
travelDurationLimit الكائن (DurationLimit) تمثّل هذه السمة حدًا أقصى ثابتًا أو مرنًا لإجمالي مدة الرحلة (باستثناء وقت الانتظار أو وقت تقديم الخدمة) للمركبة.
travelDurationMultiple الرقم المضاعف الذي يتم تطبيقه على أوقات السفر (مثلاً، يؤدي استخدام عامل الضرب 1.5 إلى إبطاء السفر بنسبة% 50).
travelMode enum (TravelMode) وسيلة النقل (مثلاً DRIVING، WALKING). يؤثر ذلك في أوقات السفر والمسافات.
unloadingPolicy enum (UnloadingPolicy) تحدّد ترتيب التفريغ (مثلاً، ‫LIFO أو LAST_IN_FIRST_OUT).
usedIfRouteIsEmpty قيمة منطقية (true/false) إذا كانت القيمة true، تُعتبر المركبة مستعمَلة حتى بدون شحنات. ويتحمّل تكاليف ثابتة ويتنقّل بين موقعَي البداية والنهاية.

نص الاستجابة

بنية البيانات في نص الاستجابة

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

  • OptimizeToursResponse: عنصر الاستجابة ذو المستوى الأعلى الذي يحتوي على المسارات والمقاييس المحسّنة.
    • Metrics: إحصاءات التكلفة والتنفيذ الإجمالية للحلّ.
    • ShipmentRoute: تسلسل الزيارات ومسار التنقّل المحدّدَين لمركبة واحدة
      • Visit: محطة على مسار لتنفيذ عملية استلام أو تسليم
      • Transition: مسار السفر ومدته بين محطتَي توقّف على الطريق
      • AggregatedMetrics: إجمالي القيم المجمّعة للمدة والمسافة والمقاييس الأخرى يمكن أن يتوفّر هذا العنصر في كل من Metrics وShipmentRoute.
أحد الوالدين المَعلمة نوع مكان الإقامة الوصف
OptimizeToursResponse metrics الكائن (Metrics) مقاييس مجمّعة للحلّ، بما في ذلك التكلفة الإجمالية والمسافة الإجمالية والمدة الإجمالية وعدد مرات استخدام المركبة
requestLabel سلسلة التصنيف الذي تم نسخه من الحقل label في الطلب يُستخدَم لربط الردّ بالطلب الأصلي.
routes[] مصفوفة من العناصر (ShipmentRoute) قائمة المسارات التي تم احتسابها لكل مركبة يحتوي على إدخال لكل مركبة، بغض النظر عن الاستخدام.
skippedShipments[] مصفوفة من العناصر (SkippedShipment) قائمة بالشحنات التي تم تخطّيها (لم يتم تقديم الخدمة لها)، بالإضافة إلى أسباب تخطّيها
validationErrors[] مصفوفة من العناصر (OptimizeToursValidationError) قائمة بأخطاء التحقّق من الصحة التي تم العثور عليها في نموذج الإدخال يتم ملء هذا الحقل إذا تم ضبط solvingMode على VALIDATE_ONLY، أو إذا حدثت أخطاء أثناء حلّ التحدي.
Metrics
(جزء من OptimizeToursResponse)
aggregatedRouteMetrics الكائن (AggregatedMetrics) إحصاءات مجمّعة على مستوى جميع المسارات، مثل إجمالي مسافة السفر وإجمالي المدة وأوقات الانتظار
costs خريطة (المفتاح: سلسلة، القيمة: رقم) تفاصيل التكاليف حسب النوع (مثل "model.vehicles.cost_per_kilometer", "model.shipments.penalty_cost").
earliestVehicleStartTime الطابع الزمني وقت البدء الأبكر بين جميع المركبات المستخدَمة
latestVehicleEndTime الطابع الزمني تمثّل هذه السمة آخر وقت انتهاء بين جميع المركبات المستخدَمة.
skippedMandatoryShipmentCount عدد صحيح عدد الشحنات الإلزامية التي تم تخطّيها
totalCost الرقم التكلفة الإجمالية للحلّ، وهي مجموع تكاليف جميع المسارات وعقوبات الشحنات التي تمّ تخطّيها.
usedVehicleCount عدد صحيح تمثّل هذه السمة عدد المركبات المستخدَمة في الحلّ.
AggregatedMetrics
(جزء من Metrics وShipmentRoute)
breakDuration المدة إجمالي مدة الاستراحات التي تم أخذها على جميع المسارات
costs خريطة (المفتاح: سلسلة، القيمة: رقم) تفاصيل التكاليف حسب النوع (مثل "model.vehicles.cost_per_kilometer", "model.shipments.penalty_cost").
delayDuration المدة إجمالي مدة التأخير في جميع المسارات
earliestVehicleStartTime الطابع الزمني وقت البدء الأبكر بين جميع المركبات المستخدَمة
latestVehicleEndTime الطابع الزمني تمثّل هذه السمة آخر وقت انتهاء بين جميع المركبات المستخدَمة.
maxLoads خريطة (المفتاح: سلسلة، القيمة: VehicleLoad) الحِمل الأقصى الذي تحمله أي مركبة في أي نقطة في الحل، ويتم تحديد المفتاح حسب نوع الحِمل.
performedShipmentCount عدد صحيح إجمالي عدد الشحنات التي تمّت في جميع المركبات
skippedMandatoryShipmentCount عدد صحيح عدد الشحنات الإلزامية التي تم تخطّيها
totalCost الرقم التكلفة الإجمالية للحلّ، وهي مجموع تكاليف جميع المسارات وعقوبات الشحنات التي تمّ تخطّيها.
totalDuration المدة إجمالي مدة جميع المسارات (السفر والانتظار والتأخير والاستراحة والزيارة)
travelDistanceMeters الرقم إجمالي مسافة السفر بالأمتار على مستوى جميع الطرق
travelDuration المدة إجمالي مدة السفر على جميع المسارات
usedVehicleCount عدد صحيح تمثّل هذه السمة عدد المركبات المستخدَمة في الحلّ.
visitDuration المدة إجمالي المدة التي تمّ قضاؤها في إجراء الزيارات (التحميل/إلغاء التحميل) على مستوى جميع المسارات
waitDuration المدة إجمالي مدة الانتظار على جميع الطرق
ShipmentRoute
(جزء من OptimizeToursResponse)
breaks[] مصفوفة من العناصر (Break) قائمة بالاستراحات التي أخذتها المركبة أثناء المسار
hasTrafficInfeasibilities قيمة منطقية (true/false) تشير هذه السمة إلى ما إذا كان المسار يتضمّن أي مشاكل متعلّقة بحركة المرور.
metrics الكائن (AggregatedMetrics) مقاييس خاصة بهذا المسار، مثل إجمالي المسافة والمدة المستغرقة في الرحلة
routeCosts خريطة (المفتاح: سلسلة، القيمة: رقم) تفاصيل التكاليف لهذا المسار المفاتيح هي أنواع التكاليف (مثل "cost_per_hour")، والقيم هي المبالغ.
routePolyline الكائن (EncodedPolyline) تمثّل هذه السلسلة المتعددة الخطوط المرمّزة المسار الكامل للطريق جغرافيًا.
routeTotalCost الرقم التكلفة الإجمالية للمسار، وهي مجموع كل التكاليف في خريطة routeCosts
transitions[] مصفوفة من العناصر (Transition) قائمة مرتبة من عمليات الانتقال (أجزاء الرحلة) التي تربط الزيارات.
vehicleEndTime الطابع الزمني الوقت الذي تنتهي فيه المركبة من مسارها
vehicleIndex عدد صحيح فهرس المركبة في المصدر ShipmentModel الذي يسلك هذا المسار
vehicleLabel سلسلة التصنيف الذي يحدّده المستخدم للمركبة، ويتم نسخه من نموذج الطلب.
vehicleStartTime الطابع الزمني الوقت الذي تبدأ فيه المركبة مسارها
visits[] مصفوفة من العناصر (Visit) التسلسل المرتّب للزيارات (عمليات الاستلام والتسليم) التي نفذتها المركبة على هذا المسار
Visit
(جزء من ShipmentRoute)
detour المدة يشير ذلك إلى الوقت الإضافي الذي استغرقته هذه الزيارة مقارنةً بالمسار المباشر بين الزيارتين السابقة والتالية.
isPickup قيمة منطقية (true/false) إذا كانت القيمة true، تكون هذه الزيارة عبارة عن عملية استلام. إذا كانت القيمة false، يكون نوع الحدث هو "تسليم".
loadDemands خريطة (المفتاح: سلسلة، القيمة: Load) متطلبات التحميل التي تم استيفاؤها من خلال هذه الزيارة (مثل -1 للتسليم) هذه نسخة من متطلبات تحميل VisitRequest ذات الصلة.
shipmentIndex عدد صحيح فهرس حقل Shipment في نموذج المصدر الذي تستخدمه هذه الزيارة.
shipmentLabel سلسلة تم نسخ ملصق الشحنة من ShipmentModel.
startTime الطابع الزمني الوقت المُجدوَل لبدء الزيارة.
visitLabel سلسلة تصنيف طلب الزيارة، تم نسخه من VisitRequest في النموذج.
visitRequestIndex عدد صحيح فهرس VisitRequest في قائمة استلام الشحنة أو تسليمها الذي تتوافق معه هذه الزيارة.
Transition
(جزء من ShipmentRoute)
breakDuration المدة مدة الاستراحات التي تم أخذها خلال عملية الانتقال هذه
delayDuration المدة مدة التأخير الذي حدث أثناء هذا الانتقال (على سبيل المثال، الوصول مبكرًا والانتظار لفترة زمنية).
routePolyline الكائن (EncodedPolyline) خط متعدد الأضلاع مرمّز يمثّل مسار هذا الانتقال المحدّد.
routeToken سلسلة رمز مميّز غير شفاف يمكن تمريره إلى حزمة تطوير البرامج (SDK) الخاصة بخدمة "التنقّل من Google" لإعادة إنشاء المسار أثناء التنقّل.
startTime الطابع الزمني وقت بدء هذا الانتقال
totalDuration المدة إجمالي مدة الانتقال، بما في ذلك السفر والانتظار والاستراحات وحالات التأخير
trafficInfoUnavailable قيمة منطقية (true/false) إذا كانت القيمة true، يشير ذلك إلى أنّ بيانات الزيارات لم تكن متاحة لهذا الانتقال.
travelDistanceMeters الرقم المسافة المقطوعة أثناء هذا الانتقال، بالمتر
travelDuration المدة مدة السفر خلال هذه الفترة الانتقالية
vehicleLoads خريطة (المفتاح: سلسلة، القيمة: VehicleLoad) الحِمل الذي تحمله المركبة أثناء هذا الانتقال، ويتم تحديد مفتاحه حسب نوع الحِمل (مثلاً، "الوزن").
waitDuration المدة مدة الانتظار قبل بدء الزيارة التالية