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.
  • في حال ضبط avoidUTurns على "صحيح"، يجب ضبط injectedSolutionLocationToken للزيارات ذات الصلة.

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

object (InjectedSolutionConstraint)

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

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

object (ShipmentRoute)

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

اعتبارًا من تشرين الثاني (نوفمبر) 2020، لا يتمّ ملء خطوط البوليجون إلا للمسارات غير الفارغة، ويتطلّب ذلك ضبط populatePolylines على "صحيح".

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

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

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

boolean

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

  • يستخدم 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

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

يجب الحصول على إذن إدارة الهوية وإمكانية الوصول التالي في مورد "parent":

  • routeoptimization.locations.use

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