Method: projects.locations.optimizeTours

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

يتكوّن نموذج ShipmentModel بشكلٍ أساسي من Shipment التي يجب تنفيذها وVehicles التي يمكن استخدامها لنقل 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

إذا كانت القيمة هي true:

  • استخدام ShipmentRoute.vehicle_label بدلاً من vehicleIndex لمطابقة المسارات في الحل الذي تم حقنه مع المركبات الواردة في الطلب إعادة استخدام ربط ShipmentRoute.vehicle_index الأصلي بـ ShipmentRoute.vehicle_index الجديد لتعديل ConstraintRelaxation.vehicle_indices إذا لم يكن فارغًا، ولكن يجب أن تكون عملية الربط واضحة (أي يجب ألا تتشارك ShipmentRoute عدة عناصر vehicleIndex الأصلية نفسها).
  • استخدام ShipmentRoute.Visit.shipment_label بدلاً من shipmentIndex لمطابقة الزيارات في الحل الذي تم حقنه مع الشحنات الواردة في الطلب
  • تستخدم SkippedShipment.label بدلاً من SkippedShipment.index لمطابقة الشحنات التي تم تخطّيها في الحلّ الذي تم حقنه مع شحنات الطلبات.

ينطبق هذا التفسير على الحقول 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

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

string

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

number

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

integer

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

نص الاستجابة

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

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

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

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