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)

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

بالنسبة إلى الطلبات غير المتزامنة، سينشئ الخادم حلاً (إن أمكن) قبل انتهاء المهلة.
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، لا يؤدي هذا إلا إلى تعبئة الخطوط المتعدّدة للمسارات غير الفارغة ويتطلّب ضبط populatePolylines على "صحيح".

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

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

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

boolean

إذا كانت القيمة صحيحة:

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

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

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

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

ملاحظة: يجب أن يضمن المتصل أنّ كل Vehicle.label (resp. 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

يتم اقتطاع عدد أخطاء التحقّق من الصحة التي يتم عرضها. يتم عادةً إرفاق هذه الأخطاء بحمولة خطأ 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

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

يتطلّب ذلك إذن إدارة الهوية وإمكانية الوصول التالي في المورد parent:

  • routeoptimization.locations.use

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