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

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

• نص الطلب
• نص الاستجابة

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

نص الطلب

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

• ‫OptimizeToursRequest: كائن الطلب ذو المستوى الأعلى الذي يحتوي على النموذج ومَعلمات الحلّ
  • ShipmentModel: بنية البيانات الأساسية التي تحتوي على الشحنات والمركبات والقيود العامة
    • ‫Shipment: مهمة تتضمّن عمليات استلام وتسليم
      • ‫VisitRequest: الموقع الجغرافي والقيود المفروضة على عملية الاستلام أو التسليم
    • ‫Vehicle: مركبة متاحة لتنفيذ الشحنات

أحد الوالدين	المَعلمة	نوع مكان الإقامة	الوصف
OptimizeToursRequest	allowLargeDeadlineDespiteInterruptionRisk	قيمة منطقية (true/false)	إذا كانت القيمة true، تتم معالجة الطلب حتى إذا تم ضبط المهلة على قيمة كبيرة (أطول من 30 دقيقة) قد تؤدي إلى انقطاع محتمل في الخادم.
	considerRoadTraffic	قيمة منطقية (true/false)	إذا كانت القيمة true، يتم استخدام بيانات حركة المرور لتحديد المسار. إذا كانت القيمة "خطأ"، يتم استخدام سرعات شبكة الطرق فقط.
	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[]	map (key: integer, value: number)	التكاليف الإضافية التي يتم تحمّلها في حال استخدام مركبة معيّنة لنقل هذه الشحنة
	costsPerVehicleIndices[]	مصفوفة من الأعداد الصحيحة	فهارس المركبات التي تنطبق عليها قيم costsPerVehicle.
	deliveries[]	مصفوفة من العناصر (VisitRequest)	بدائل لتسليم الشحنة
	ignore	قيمة منطقية (true/false)	إذا كانت القيمة true، يتم تجاهل الشحنة ولا يتم استخدامها في التحسين.
	label	سلسلة	تصنيف يحدّده المستخدم لتحديد الشحنة، ويتم عرضه في الردّ
	loadDemands	map (key: string, value: 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	map (key: string, value: Load)	الطلبات التي تحدّد تغيير الحمولة في هذه المحطة (مثلاً، -1 لتسليم طرد)
	tags[]	مصفوفة سلاسل	العلامات المرفقة بطلب الزيارة هذا يتم استخدام هذه المعلومات لاحتساب مدة الرحلة بين هذه الزيارة والزيارات الأخرى باستخدام transitionAttributes.
	timeWindows[]	مصفوفة من العناصر (TimeWindow)	النوافذ الزمنية المسموح بها للوصول إلى هذه الزيارة
	visitTypes[]	مصفوفة سلاسل	سلاسل تصف نوع الزيارة (مثل "تسليم" أو "تركيب"). تُستخدَم لتطبيق سمة extraVisitDurationForVisitType من نموذج المركبة.
‫Vehicle (جزء من "ShipmentModel")	breakRule	كائن (BreakRule)	تحدّد قواعد الاستراحات (مثل استراحة الغداء الإلزامية).
	costPerHour	الرقم	التكلفة لكل ساعة من إجمالي مدة المسار
	costPerKilometer	الرقم	التكلفة لكل كيلومتر مقطوع
	costPerTraveledHour	الرقم	التكلفة في الساعة أثناء تحرّك المركبة
	endLocation	كائن (LatLng)	الموقع الجغرافي النهائي كإحداثيات خطوط العرض/الطول
	endTags[]	مصفوفة سلاسل	علامات تحدّد الحالة النهائية للمركبة، وتُستخدَم لسمات الانتقال.
	endTimeWindows[]	مصفوفة من العناصر (TimeWindow)	النوافذ المسموح بها للمركبة لإنهاء مسارها
	endWaypoint	كائن (Waypoint)	الموقع الجغرافي النهائي باستخدام نقطة على المسار (الإحداثيات أو رقم تعريف المكان)
	extraVisitDurationForVisitType	map (key: string, value: Duration)	تضيف هذه السمة مدة إضافية إلى الزيارات استنادًا إلى visitType.
	fixedCost	الرقم	تكلفة ثابتة يتم تطبيقها في حال استخدام المركبة، بغض النظر عن مسافة المسار أو مدته
	ignore	قيمة منطقية (true/false)	إذا كانت القيمة true، يتم تجاهل المركبة ولا يتم استخدامها في التحسين.
	label	سلسلة	تصنيف يحدّده المستخدم للمركبة، ويتم عرضه في الاستجابة.
	loadLimits	map (key: string, value: 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	map (key: string, value: number)	تفاصيل التكاليف حسب النوع (مثل "model.vehicles.cost_per_kilometer" و"model.shipments.penalty_cost")
	earliestVehicleStartTime	الطابع الزمني	أقرب وقت بدء بين جميع المركبات المستخدَمة
	latestVehicleEndTime	الطابع الزمني	أحدث وقت انتهاء بين جميع المركبات المستخدَمة.
	skippedMandatoryShipmentCount	عدد صحيح	عدد الشحنات الإلزامية التي تم تخطّيها
	totalCost	الرقم	التكلفة الإجمالية للحلّ، وهي مجموع تكاليف جميع المسارات وغرامات الشحنات التي تم تخطّيها.
	usedVehicleCount	عدد صحيح	عدد المركبات المستخدَمة في الحلّ
AggregatedMetrics (جزء من "Metrics" و"ShipmentRoute")	breakDuration	المدة	إجمالي مدة الاستراحات التي تم أخذها في جميع المسارات
	costs	map (key: string, value: number)	تفاصيل التكاليف حسب النوع (مثل "model.vehicles.cost_per_kilometer" و"model.shipments.penalty_cost")
	delayDuration	المدة	إجمالي مدة التأخير في جميع المسارات
	earliestVehicleStartTime	الطابع الزمني	أقرب وقت بدء بين جميع المركبات المستخدَمة
	latestVehicleEndTime	الطابع الزمني	أحدث وقت انتهاء بين جميع المركبات المستخدَمة.
	maxLoads	map (key: string, value: VehicleLoad)	الحد الأقصى للحمولة التي تحملها أي مركبة في أي نقطة في الحلّ، ويتم تحديدها حسب نوع الحمولة.
	performedShipmentCount	عدد صحيح	إجمالي عدد الشحنات التي تم إجراؤها على مستوى جميع المركبات
	skippedMandatoryShipmentCount	عدد صحيح	عدد الشحنات الإلزامية التي تم تخطّيها
	totalCost	الرقم	التكلفة الإجمالية للحلّ، وهي مجموع تكاليف جميع المسارات وغرامات الشحنات التي تم تخطّيها.
	totalDuration	المدة	إجمالي مدة جميع المسارات (السفر + الانتظار + التأخير + الاستراحة + الزيارة).
	travelDistanceMeters	الرقم	إجمالي مسافة السفر بالأمتار في جميع المسارات
	travelDuration	المدة	إجمالي مدة السفر على مستوى جميع المسارات
	usedVehicleCount	عدد صحيح	عدد المركبات المستخدَمة في الحلّ
	visitDuration	المدة	إجمالي المدة التي تم قضاؤها في إجراء الزيارات (التحميل/التفريغ) في جميع المسارات
	waitDuration	المدة	إجمالي مدة الانتظار على مستوى جميع المسارات
‫ShipmentRoute (جزء من "OptimizeToursResponse")	breaks[]	مصفوفة من العناصر (Break)	قائمة بالاستراحات التي أخذتها المركبة أثناء المسار
	hasTrafficInfeasibilities	قيمة منطقية (true/false)	تشير هذه السمة إلى ما إذا كان المسار يتضمّن أي مشاكل متعلّقة بحركة المرور.
	metrics	كائن (AggregatedMetrics)	المقاييس الخاصة بهذا المسار، مثل إجمالي المسافة والمدة التي تم قطعها
	routeCosts	map (key: string, value: number)	تفاصيل التكاليف لهذا المسار المفاتيح هي أنواع التكلفة (مثل "cost_per_hour")، والقيم هي المبالغ.
	routePolyline	كائن (EncodedPolyline)	الخطوط المتعدّدة المرمّزة التي تمثّل المسار الكامل للمسار جغرافيًا
	routeTotalCost	الرقم	التكلفة الإجمالية للمسار، وهي مجموع كل التكاليف في خريطة routeCosts.
	transitions[]	مصفوفة من العناصر (Transition)	قائمة مع ترتيب لعمليات الانتقال (مراحل السفر) التي تربط بين الزيارات
	vehicleEndTime	الطابع الزمني	الوقت الذي تنتهي فيه المركبة من مسارها
	vehicleIndex	عدد صحيح	فهرس المركبة في المصدر ShipmentModel التي تسلك هذا المسار.
	vehicleLabel	سلسلة	التصنيف الذي يحدّده المستخدم للمركبة، والذي يتم نسخه من نموذج الطلب
	vehicleStartTime	الطابع الزمني	الوقت الذي تبدأ فيه المركبة مسارها
	visits[]	مصفوفة من العناصر (Visit)	التسلسل المرتّب للزيارات (عمليات الاستلام والتسليم) التي تنفّذها المركبة على هذا المسار
‫Visit (جزء من "ShipmentRoute")	detour	المدة	الوقت الإضافي الذي تستغرقه هذه الزيارة مقارنةً بالمسار المباشر بين الزيارتَين السابقة والتالية
	isPickup	قيمة منطقية (true/false)	إذا كانت القيمة true، تكون هذه الزيارة لاستلام الطلب. إذا كانت القيمة خطأ، يعني ذلك أنّ الطلب هو للتوصيل.
	loadDemands	map (key: string, value: 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	map (key: string, value: VehicleLoad)	الحمولة التي تنقلها المركبة خلال هذه الرحلة، ويتم تحديدها حسب نوع الحمولة (مثل "الوزن").
	waitDuration	المدة	المدة التي يتم قضاؤها في الانتظار قبل بدء الزيارة التالية