Method: projects.locations.optimizeTours

ترسل هذه الطريقة OptimizeToursRequest يحتوي على ShipmentModel وتعرض OptimizeToursResponse يحتوي على ShipmentRoute، وهي مجموعة من المسارات التي يجب أن تسلكها المركبات لتقليل التكلفة الإجمالية.

يتألف نموذج ShipmentModel بشكل أساسي من Shipment يجب تنفيذها وVehicle يمكن استخدامها لنقل Shipment. تُسند ShipmentRoute Shipment إلى Vehicle. وبشكل أكثر تحديدًا، يتم تخصيص سلسلة من Visit لكل مركبة، حيث يتوافق Visit مع VisitRequest، وهو عملية استلام أو تسليم Shipment.

الهدف هو توفير عملية ربط بين ShipmentRoute وVehicle تقلّل من التكلفة الإجمالية التي تتضمّن العديد من المكوّنات المحدّدة في ShipmentModel.

طلب HTTP

POST https://routeoptimization.googleapis.com/v1/{parent=projects/*/locations/*}:optimizeTours

يستخدم عنوان URL بنية تحويل الترميز إلى gRPC.

مَعلمات المسار

المعلمات
parent

string

الحقل مطلوب. استهداف مشروع أو موقع جغرافي لإجراء مكالمة

التنسيق:

  • projects/{project-id}
  • projects/{project-id}/locations/{location-id}

في حال عدم تحديد موقع جغرافي، سيتم اختيار منطقة تلقائيًا.

نص الطلب

يتضمن نص الطلب بيانات بالبنية التالية:

تمثيل JSON 
{
  "timeout": string,
  "model": {
    object (ShipmentModel)
  },
  "solvingMode": enum (SolvingMode),
  "searchMode": enum (SearchMode),
  "injectedFirstSolutionRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "injectedSolutionConstraint": {
    object (InjectedSolutionConstraint)
  },
  "refreshDetailsRoutes": [
    {
      object (ShipmentRoute)
    }
  ],
  "interpretInjectedSolutionsUsingLabels": boolean,
  "considerRoadTraffic": boolean,
  "populatePolylines": boolean,
  "populateTransitionPolylines": boolean,
  "allowLargeDeadlineDespiteInterruptionRisk": boolean,
  "useGeodesicDistances": boolean,
  "label": string,
  "geodesicMetersPerSecond": number,
  "maxValidationErrors": integer
}
الحقول
timeout

string (Duration format)

في حال ضبط مهلة الاستجابة هذه، يعرض الخادم ردًا قبل انقضاء مدة المهلة أو قبل بلوغ الموعد النهائي الذي حدّده الخادم للطلبات المتزامنة، أيهما أقرب.

بالنسبة إلى الطلبات غير المتزامنة، سينشئ الخادم حلاً (إذا أمكن ذلك) قبل انقضاء المهلة.

مدة بالثواني مع ما يصل إلى تسعة أرقام كسور، وتنتهي بـ "s". مثال: "3.5s"
model

object (ShipmentModel)

نموذج الشحن المطلوب حله
solvingMode

enum (SolvingMode)

يكون وضع الحلّ تلقائيًا DEFAULT_SOLVE (0).
searchMode

enum (SearchMode)

وضع البحث المستخدَم لحلّ الطلب
injectedFirstSolutionRoutes[]

object (ShipmentRoute)

توجيه خوارزمية التحسين للعثور على حلّ أوّلي مشابه لحلّ سابق

يتم تقييد النموذج عند إنشاء الحلّ الأول. يتم ضِمنيًا تخطّي أي شحنات لم يتم تنفيذها على مسار في الحل الأول، ولكن يمكن تنفيذها في الحلول اللاحقة.

يجب أن يستوفي الحل بعض افتراضات الصلاحية الأساسية:

  • بالنسبة إلى جميع الطرق، يجب أن يكون vehicleIndex ضمن النطاق وألّا يكون مكررًا.
  • بالنسبة إلى جميع الزيارات، يجب أن يكون shipmentIndex وvisitRequestIndex ضمن النطاق.
  • لا يمكن الإشارة إلى شحنة إلا في مسار واحد.
  • يجب استلام شحنة الاستلام والتسليم قبل تسليمها.
  • لا يمكن تنفيذ أكثر من بديل واحد لاستلام الشحنة أو تسليمها.
  • بالنسبة إلى جميع المسارات، تتزايد الأوقات (أي vehicleStartTime <= visits[0].start_time <= visits[1].start_time ... <= vehicleEndTime).
  • لا يمكن إجراء عملية شحن إلا على مركبة مسموح بها. يُسمح بالمركبة إذا كان Shipment.allowed_vehicle_indices فارغًا أو إذا كان vehicleIndex مضمّنًا في Shipment.allowed_vehicle_indices.

إذا كان الحلّ الذي تم إدخاله غير ممكن، لن يتم بالضرورة عرض خطأ في التحقّق من الصحة، بل قد يتم عرض خطأ يشير إلى عدم الإمكانية.
injectedSolutionConstraint

object (InjectedSolutionConstraint)

تقييد خوارزمية التحسين للعثور على حل نهائي مشابه لحل سابق على سبيل المثال، يمكن استخدام ذلك لتجميد أجزاء من المسارات التي تم إكمالها أو التي سيتم إكمالها ولكن يجب عدم تعديلها.

إذا كان الحلّ الذي تم إدخاله غير ممكن، لن يتم بالضرورة عرض خطأ في التحقّق من الصحة، بل قد يتم عرض خطأ يشير إلى عدم الإمكانية.
refreshDetailsRoutes[]

object (ShipmentRoute)

في حال عدم توفّر مسار فارغ، سيتم إعادة تحميل المسارات المحدّدة بدون تعديل التسلسل الأساسي للزيارات أو أوقات السفر، وسيتم تعديل التفاصيل الأخرى فقط. لا يحلّ هذا الإجراء المشكلة في النموذج.

اعتبارًا من 2020/11، لا يتم ملء الخطوط المتعددة إلا للطرق غير الفارغة، ويجب أن تكون قيمة populatePolylines صحيحة.

قد تكون حقول routePolyline للمسارات التي تم إدخالها غير متوافقة مع المسار transitions.

يجب عدم استخدام هذا الحقل مع injectedFirstSolutionRoutes أو injectedSolutionConstraint.

ليس لـ Shipment.ignore وVehicle.ignore أي تأثير في السلوك. لا يزال يتم إنشاء خطوط متعددة الأضلاع بين جميع الزيارات في جميع المسارات غير الفارغة بغض النظر عمّا إذا كان يتم تجاهل الشحنات أو المركبات ذات الصلة.
interpretInjectedSolutionsUsingLabels

boolean

إذا كان ذلك صحيحًا:

ينطبق هذا التفسير على الحقول injectedFirstSolutionRoutes وinjectedSolutionConstraint وrefreshDetailsRoutes. يمكن استخدامها عندما تتغير مؤشرات الشحنات أو المركبات في الطلب منذ إنشاء الحلّ، ربما بسبب إزالة شحنات أو مركبات من الطلب أو إضافتها إليه.

إذا كانت القيمة هي true، يجب ألا تظهر التصنيفات في الفئات التالية أكثر من مرة واحدة في فئتها:

إذا لم يتطابق vehicleLabel في الحلّ الذي تم إدخاله مع مركبة مطلوبة، تتم إزالة المسار المطابق من الحلّ مع محطاته. إذا لم يتطابق shipmentLabel في الحلّ الذي تمّ إدخاله مع شحنة طلب، تتمّ إزالة الزيارة المطابقة من الحلّ. إذا لم يتطابق SkippedShipment.label في الحلّ الذي تم إدخاله مع شحنة الطلب، تتم إزالة SkippedShipment من الحلّ.

قد تؤدي إزالة زيارات مسار أو مسارات كاملة من حلّ تم إدخاله إلى التأثير في القيود الضمنية، ما قد يؤدي إلى تغيير في الحلّ أو حدوث أخطاء في التحقّق من الصحة أو عدم إمكانية التنفيذ.

ملاحظة: على المتّصل التأكّد من أنّ كل Vehicle.label (أو Shipment.label) يحدّد بشكل فريد كيان مركبة (أو شحنة) مستخدَم في الطلبَين ذَوَي الصلة: الطلب السابق الذي أنتج OptimizeToursResponse المستخدَم في الحلّ المُدرَج والطلب الحالي الذي يتضمّن الحلّ المُدرَج. لا تكفي عمليات التحقّق من التفرد الموضّحة أعلاه لضمان استيفاء هذا الشرط.
considerRoadTraffic

boolean

ضَع تقدير حركة المرور في الاعتبار عند احتساب الحقول ShipmentRoute وTransition.travel_duration وVisit.start_time وvehicleEndTime، وعند ضبط الحقل ShipmentRoute.has_traffic_infeasibilities، وعند احتساب الحقل OptimizeToursResponse.total_cost.
populatePolylines

boolean

في حال ضبطها على "صحيح"، ستتم تعبئة الخطوط المتعددة في الردود ShipmentRoute.
populateTransitionPolylines

boolean

إذا كانت القيمة "صحيح"، سيتم ملء الخطوط المتعددة ورموز المسار المميزة في الرد ShipmentRoute.transitions.
allowLargeDeadlineDespiteInterruptionRisk

boolean

في حال ضبط هذه السياسة، يمكن أن يكون للطلب موعد نهائي (راجِع https://grpc.io/blog/deadlines) يصل إلى 60 دقيقة. وبخلاف ذلك، يكون الحدّ الأقصى للموعد النهائي 30 دقيقة فقط. يُرجى العِلم أنّ الطلبات التي تستغرق وقتًا طويلاً تكون أكثر عرضة للانقطاع (وإن كان احتمال حدوث ذلك ضئيلاً).
useGeodesicDistances

boolean

في حال ضبط القيمة على true، سيتم احتساب مسافات التنقّل باستخدام المسافات الجيوديسية بدلاً من مسافات "خرائط Google"، وسيتم احتساب مُدد التنقّل باستخدام المسافات الجيوديسية مع سرعة محدّدة بواسطة geodesicMetersPerSecond.
label

string

تصنيف يمكن استخدامه لتحديد هذا الطلب، ويتم إرجاعه في OptimizeToursResponse.request_label.
geodesicMetersPerSecond

number

عندما تكون قيمة useGeodesicDistances صحيحة، يجب ضبط هذا الحقل وتحديد السرعة المستخدَمة لاحتساب مدة الرحلات. يجب أن تكون قيمته 1.0 متر/ثانية على الأقل.
maxValidationErrors

integer

يتم اقتطاع عدد أخطاء التحقّق من الصحة التي يتم عرضها. عادةً ما تكون هذه الأخطاء مرفقة بحِزمة بيانات خطأ INVALID_ARGUMENT كتفاصيل خطأ BadRequest (https://cloud.google.com/apis/design/errors#error_details)، ما لم يكن solvingMode=VALIDATE_ONLY: راجِع الحقل OptimizeToursResponse.validation_errors. القيمة التلقائية هي 100 والحد الأقصى هو 10,000.

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيحتوي نصها على مثال OptimizeToursResponse.

نطاقات الأذونات

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/cloud-platform

أذونات "إدارة الهوية وإمكانية الوصول"

يتطلّب هذا الإجراء إذن إدارة الهوية وإمكانية الوصول (IAM) التالي على مورد parent:

  • routeoptimization.locations.use

لمزيد من المعلومات، يُرجى الاطّلاع على مستندات إدارة الهوية وإمكانية الوصول.