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

تحتوي الصفحة التالية على جداول المَعلمات مرتّبة أبجديًا لمكوّنات طريقة 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 المدة المدة القصوى التي يجب أن يعمل خلالها أداة الحل (مثلاً، "30 ثانية" أو "300 ثانية").
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[] مصفوفة سلاسل سلاسل تصف نوع الزيارة (مثلاً، "توصيل" أو "تركيب"). تُستخدَم لتطبيق 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 خريطة (المفتاح: سلسلة، القيمة: رقم) تفاصيل التكاليف لهذا المسار المفاتيح هي أنواع التكاليف (مثل "التكلفة لكل ساعة")، والقيم هي المبالغ.
routePolyline الكائن (EncodedPolyline) تمثّل هذه السلسلة المتعددة الخطوط المرمّزة المسار الكامل للطريق جغرافيًا.
routeTotalCost الرقم التكلفة الإجمالية للمسار، وهي مجموع كل التكاليف في خريطة routeCosts
transitions[] مصفوفة من العناصر (Transition) قائمة مرتبة من عمليات الانتقال (أجزاء الرحلة) التي تربط الزيارات.
vehicleEndTime الطابع الزمني الوقت الذي تنهي فيه المركبة مسارها
vehicleIndex عدد صحيح فهرس المركبة في المصدر ShipmentModel الذي ينفّذ هذا المسار
vehicleLabel سلسلة التصنيف الذي يحدّده المستخدم للمركبة، ويتم نسخه من نموذج الطلب.
vehicleStartTime الطابع الزمني الوقت الذي تبدأ فيه المركبة مسارها
visits[] مصفوفة من العناصر (Visit) التسلسل المرتّب للزيارات (عمليات الاستلام والتسليم) التي نفذتها المركبة على هذا المسار
‫Visit
(جزء من ShipmentRoute)		 detour المدة يشير ذلك إلى وقت التجول الإضافي الذي استغرقته هذه الزيارة مقارنةً بالمسار المباشر بين الزيارتين السابقة والتالية.
isPickup قيمة منطقية (true/false) إذا كانت القيمة true، تكون هذه الزيارة عبارة عن عملية استلام. إذا كانت القيمة خطأ، يكون ذلك توصيلاً.
loadDemands خريطة (المفتاح: سلسلة، القيمة: Load) طلبات التحميل التي تم استيفاؤها من خلال هذه الزيارة (مثلاً، -1 للتسليم) هذه نسخة من متطلبات تحميل VisitRequest ذات الصلة.
shipmentIndex عدد صحيح فهرس حقل Shipment في نموذج المصدر الذي تستخدمه هذه الزيارة.
shipmentLabel سلسلة تم نسخ ملصق الشحنة من ShipmentModel.
startTime الطابع الزمني الوقت المُجدوَل لبدء الزيارة.
visitLabel سلسلة تصنيف طلب الزيارة، تم نسخه من VisitRequest في النموذج.
visitRequestIndex عدد صحيح فهرس VisitRequest في قائمة استلام الشحنة أو تسليمها الذي تتوافق معه هذه الزيارة.
‫Transition
(جزء من ShipmentRoute)		 breakDuration المدة مدة الاستراحات التي تم أخذها خلال عملية الانتقال هذه
delayDuration المدة مدة التأخير الذي حدث أثناء هذا الانتقال (على سبيل المثال، الوصول مبكرًا والانتظار حتى يحين وقت النافذة الزمنية)
routePolyline الكائن (EncodedPolyline) الخط المتعدد الأضلاع المرمّز الذي يمثّل مسار هذا الانتقال المحدّد
routeToken سلسلة رمز مميّز غير شفاف يمكن تمريره إلى حزمة Google Navigation SDK لإعادة إنشاء المسار أثناء التنقّل.
startTime الطابع الزمني وقت بدء هذا الانتقال
totalDuration المدة إجمالي مدة الانتقال، بما في ذلك السفر والانتظار والاستراحات وحالات التأخير
trafficInfoUnavailable قيمة منطقية (true/false) إذا كانت القيمة true، يشير ذلك إلى أنّ بيانات الزيارات لم تكن متاحة لهذا الانتقال.
travelDistanceMeters الرقم المسافة المقطوعة أثناء هذا الانتقال، بالأمتار
travelDuration المدة مدة السفر خلال هذه الفترة الانتقالية
vehicleLoads خريطة (المفتاح: سلسلة، القيمة: VehicleLoad) الحِمل الذي تحمله المركبة أثناء هذا الانتقال، ويتم تحديد مفتاحه حسب نوع الحِمل (مثل "الوزن").
waitDuration المدة مدة الانتظار قبل بدء الزيارة التالية