REST Resource: providers.tasks

المرجع: المهمة

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

ملاحظة: تستخدم واجهات برمجة التطبيقات gRPC وREST قواعد تسمية حقول مختلفة. على سبيل المثال، يشير الحقل Task.journey_sharing_info في gRPC API والحقل Task.journeySharingInfo في REST API إلى الحقل نفسه.

تمثيل JSON 
{
  "name": string,
  "type": enum (Type),
  "state": enum (State),
  "taskOutcome": enum (TaskOutcome),
  "taskOutcomeTime": string,
  "taskOutcomeLocation": {
    object (LocationInfo)
  },
  "taskOutcomeLocationSource": enum (TaskOutcomeLocationSource),
  "trackingId": string,
  "deliveryVehicleId": string,
  "plannedLocation": {
    object (LocationInfo)
  },
  "taskDuration": string,
  "targetTimeWindow": {
    object (TimeWindow)
  },
  "journeySharingInfo": {
    object (JourneySharingInfo)
  },
  "taskTrackingViewConfig": {
    object (TaskTrackingViewConfig)
  },
  "attributes": [
    {
      object (TaskAttribute)
    }
  ]
}
الحقول
name

string

يجب أن يكون بالتنسيق providers/{provider}/tasks/{task}.
type

enum (Type)

مطلوب. غير قابل للتغيير تحدِّد هذه السمة نوع المهمة. على سبيل المثال، استراحة أو شحنة.
state

enum (State)

مطلوب. حالة التنفيذ الحالية للمَهمّة
taskOutcome

enum (TaskOutcome)

نتيجة المهمّة
taskOutcomeTime

string (Timestamp format)

الطابع الزمني الذي يشير إلى وقت ضبط مزوّد الخدمة لنتيجة Task

يستخدم معيار RFC 3339، حيث يكون الناتج الذي يتم إنشاؤه دائمًا مُعدَّلاً وفقًا لقاعدة Z ويستخدم 0 أو 3 أو 6 أو 9 أرقام عشرية. يتم أيضًا قبول العناصر غير "Z". أمثلة: "2014-10-02T15:01:23Z" أو "2014-10-02T15:01:23.045123456Z" أو "2014-10-02T15:01:23+05:30"
taskOutcomeLocation

object (LocationInfo)

الموقع الجغرافي الذي تمّ فيه ضبط نتيجة Task يتم تعديل هذه القيمة كجزء من tasks.patch. إذا لم يعدّل مقدّم الخدمة هذه القيمة صراحةً، ستعبئ Fleet Engine هذه القيمة تلقائيًا بآخر موقع جغرافي معروف للمركبة (الموقع الجغرافي الأصلي).
taskOutcomeLocationSource

enum (TaskOutcomeLocationSource)

يشير إلى مصدر قيمة taskOutcomeLocation.
trackingId

string

غير قابل للتغيير يسهّل هذا الحقل تخزين معرّف كي تتمكّن من تجنُّب استخدام عملية ربط معقّدة. لا يمكنك ضبط trackingId للمهام من النوعَين UNAVAILABLE وSCHEDULED_STOP. تخضع أرقام التعريف هذه للقيود التالية:

  • يجب أن تكون سلسلة Unicode صالحة.
  • يجب ألا يزيد طولها عن 64 حرفًا.
  • تم تسويتها وفقًا لنموذج تسويتها في يونيكود (C).
  • يجب ألّا تحتوي على أي من أحرف ASCII التالية: ‎/‎ أو ‎:‎ أو ‎?‎ أو ‎,‎ أو ‎#‎.
deliveryVehicleId

string

النتائج فقط. رقم تعريف المركبة التي تنفِّذ هذه المهمة. تخضع أرقام تعريف مركبات التسليم للقيود التالية:

  • يجب أن تكون سلسلة Unicode صالحة.
  • يجب ألا يزيد طولها عن 64 حرفًا.
  • تم تسويتها وفقًا لنموذج تسويتها في يونيكود C.
  • يجب ألّا تحتوي على أي من أحرف ASCII التالية: ‎/‎ أو ‎:‎ أو ‎?‎ أو ‎,‎ أو ‎#‎.
plannedLocation

object (LocationInfo)

غير قابل للتغيير الموقع الجغرافي الذي سيتم إكمال المهمة فيه اختيارية لـ UNAVAILABLE "مهام Google"، ولكنها مطلوبة لجميع "مهام Google" الأخرى.
taskDuration

string (Duration format)

مطلوب. غير قابل للتغيير الوقت اللازم لتنفيذ مهمة في هذا الموقع الجغرافي

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

object (TimeWindow)

الفترة الزمنية التي يجب إنجاز المهمة خلالها.
journeySharingInfo

object (JourneySharingInfo)

النتائج فقط. الحقول المتعلّقة بمشاركة الرحلة لا تتم تعبئة هذا الحقل عندما تكون الحالة CLOSED.
taskTrackingViewConfig

object (TaskTrackingViewConfig)

إعدادات تتبُّع المهام التي تحدّد عناصر البيانات التي تظهر للمستخدمين النهائيين في ظلّ أيّ ظروف
attributes[]

object (TaskAttribute)

قائمة بسمات المهام المخصّصة يجب أن يكون لكل سمة مفتاح فريد.

النوع

نوع المهمة

عمليات التعداد
TYPE_UNSPECIFIED الإعداد التلقائي هو أنّ نوع المهمة غير معروف.
PICKUP مهمة الاستلام هي الإجراء الذي يتم اتّخاذه لاستلام شحنة من العميل. يجب أن تستخدم المركبات التي تنقل الركاب من المحطة أو المركبات الفرعية نوع SCHEDULED_STOP.
DELIVERY مهمة التسليم هي الإجراء الذي يتم اتّخاذه لتسليم شحنة إلى عميل نهائي. يجب استخدام النوع SCHEDULED_STOP لعمليات تسليم المركبات في المحطة أو المركبات الإمدادية.
SCHEDULED_STOP تُستخدَم مهمة الإيقاف المُجدوَلة لأغراض التخطيط. على سبيل المثال، يمكن أن يشير ذلك إلى استلام الشحنات أو تسليمها من المركبات أو المستودعات الفرعية. ولا يُسمح باستخدامه لأي شحنات يتم استلامها أو تسليمها من عميل نهائي.
UNAVAILABLE مهمة تعني أنّ المركبة غير متاحة للصيانة على سبيل المثال، يمكن أن يحدث ذلك عندما يأخذ السائق استراحة أو عندما يتم تعبئة المركبة بالوقود.

TaskOutcomeLocationSource

هوية المصدر الذي تمّت تعبئة taskOutcomeLocation به.

عمليات التعداد
TASK_OUTCOME_LOCATION_SOURCE_UNSPECIFIED نتيجة المهمة قبل ضبطها
PROVIDER حدّد مقدّم الخدمة taskOutcomeLocation.
LAST_VEHICLE_LOCATION لم يحدّد مقدّم الخدمة taskOutcomeLocation، لذا استخدم Fleet Engine آخر موقع جغرافي معروف للمركبة.

JourneySharingInfo

حقول محددة لمشاركة الرحلة

تمثيل JSON 
{
  "remainingVehicleJourneySegments": [
    {
      object (VehicleJourneySegment)
    }
  ],
  "lastLocation": {
    object (DeliveryVehicleLocation)
  },
  "lastLocationSnappable": boolean
}
الحقول
remainingVehicleJourneySegments[]

object (VehicleJourneySegment)

تتيح لك هذه السمة تتبُّع المعلومات المتعلّقة بالمحطات التي ستتوقف عندها المركبة المحدّدة قبل إكمال هذه المهمة. يُرجى العلم أنّ هذه القائمة يمكن أن تحتوي على محطات من مهام أخرى.

يحتوي الجزء الأول، Task.journey_sharing_info.remaining_vehicle_journey_segments[0] (gRPC) أو Task.journeySharingInfo.remainingVehicleJourneySegments[0] (REST)، على معلومات عن المسار من آخر موقع معروف للسائق إلى VehicleStop القادم. تأتي عادةً معلومات المسار الحالي من تطبيق السائق، باستثناء بعض الحالات الموضّحة في مستندات DeliveryVehicle.current_route_segment. يتمّ تعبئة الشرائح الأخرى في Task.journey_sharing_info.remaining_vehicle_journey_segments (gRPC) أو Task.journeySharingInfo.remainingVehicleJourneySegments (REST) بواسطة Fleet Engine. وتقدّم هذه الشركات معلومات عن المسارات بين VehicleStops المتبقية.
lastLocation

object (DeliveryVehicleLocation)

يشير إلى آخر موقع جغرافي تم الإبلاغ عنه للمركبة المخصّصة.
lastLocationSnappable

boolean

يشير إلى ما إذا كان يمكن تثبيت lastLocation للمركبة على currentRouteSegment. تكون هذه القيمة False إذا لم يكن lastLocation أو currentRouteSegment متوفّرَين. يتم احتساب هذه القيمة بواسطة Fleet Engine. يتم تجاهل التعديلات الواردة من العملاء.

TaskTrackingViewConfig

رسالة الضبط التي تحدّد الحالات التي يجب فيها أن يكون عنصر بيانات إحدى المهام مرئيًا للمستخدمين النهائيين.

تمثيل JSON 
{
  "routePolylinePointsVisibility": {
    object (VisibilityOption)
  },
  "estimatedArrivalTimeVisibility": {
    object (VisibilityOption)
  },
  "estimatedTaskCompletionTimeVisibility": {
    object (VisibilityOption)
  },
  "remainingDrivingDistanceVisibility": {
    object (VisibilityOption)
  },
  "remainingStopCountVisibility": {
    object (VisibilityOption)
  },
  "vehicleLocationVisibility": {
    object (VisibilityOption)
  }
}
الحقول
routePolylinePointsVisibility

object (VisibilityOption)

الحقل الذي يحدّد الحالات التي يمكن فيها ظهور نقاط الخطوط المتعددة للمسار في حال عدم تحديد هذا الحقل، سيتم استخدام الإعدادات التلقائية لمستوى مستوى المشروع لمستوى مستوى المشروع لهذه البيانات.
estimatedArrivalTimeVisibility

object (VisibilityOption)

الحقل الذي يحدّد الحالات التي يمكن فيها عرض الوقت المقدَّر للوصول في حال عدم تحديد هذا الحقل، سيتم استخدام الإعدادات التلقائية لمستوى مستوى المشروع لمستوى مستوى المشروع لهذه البيانات.
estimatedTaskCompletionTimeVisibility

object (VisibilityOption)

الحقل الذي يحدّد الحالات التي يمكن فيها ظهور الوقت المقدَّر لإكمال المهمة في حال عدم تحديد هذا الحقل، سيتم استخدام الإعدادات التلقائية لمستوى مستوى المشروع لمستوى مستوى المشروع لهذه البيانات.
remainingDrivingDistanceVisibility

object (VisibilityOption)

الحقل الذي يحدّد الحالات التي يمكن فيها عرض المسافة المتبقّية للقيادة في حال عدم تحديد هذا الحقل، سيتم استخدام الإعدادات التلقائية لمستوى مستوى المشروع لمستوى مستوى المشروع لهذه البيانات.
remainingStopCountVisibility

object (VisibilityOption)

الحقل الذي يحدّد الحالات التي يمكن فيها ظهور عدد المحطات المتبقية في حال عدم تحديد هذا الحقل، سيتم استخدام الإعدادات التلقائية لمستوى مستوى المشروع لمستوى مستوى المشروع لهذه البيانات.
vehicleLocationVisibility

object (VisibilityOption)

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

VisibilityOption

رسالة الخيار التي تحدّد الحالات التي يجب أن يكون فيها عنصر البيانات مرئيًا للمستخدمين النهائيين.

تمثيل JSON 
{

  // Union field visibility_option can be only one of the following:
  "remainingStopCountThreshold": integer,
  "durationUntilEstimatedArrivalTimeThreshold": string,
  "remainingDrivingDistanceMetersThreshold": integer,
  "always": boolean,
  "never": boolean
  // End of list of possible types for union field visibility_option.
}
الحقول
حقل الربط visibility_option خيار مستوى الرؤية المحدّد الذي تم اختياره يمكن أن يكون visibility_option واحدًا فقط مما يلي:
remainingStopCountThreshold

integer

يظهر عنصر البيانات هذا للمستخدمين النهائيين إذا كان عدد المحطات المتبقية <= remainingStopCountThreshold.
durationUntilEstimatedArrivalTimeThreshold

string (Duration format)

يظهر عنصر البيانات هذا للمستخدمين النهائيين إذا كان الوقت المقدَّر للوصول إلى المحطة <= الحدّ الأدنى لمدة الوصول المقدَّرة.

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

integer

يظهر عنصر البيانات هذا للمستخدمين النهائيين إذا كانت المسافة المتبقية للقيادة بالكيلومترات <= remainingDrivingDistanceMetersThreshold.
always

boolean

في حال ضبطها على "صحيح"، يكون عنصر البيانات هذا مرئيًا دائمًا للمستخدمين النهائيين بدون حدود. لا يمكن ضبط هذا الحقل على "خطأ".
never

boolean

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

الطُرق

batchCreate

 تُنشئ هذه الدالة مجموعة من عناصر Task الجديدة وتُرجعها.

create

 لإنشاء عنصر Task جديد وإرجاعه

delete

 لحذف مهمة واحدة

get

 الحصول على معلومات عن Task

list

 تحصل على جميع Task التي تستوفي معايير الفلترة المحدّدة.

patch

 تعديل بيانات Task