إنهاء المهام

تفترض هذه المستندات أنّك تعرف كيفية إنشاء المهام واستخدامها. وتقدّم أمثلة محدّدة حول كيفية إنهاء مهام الشحن على النحو التالي:

• إغلاق مهمة: يؤدي إغلاق مهمة شحن إلى تغيير حالتها إلى CLOSED و يشير إلى أنّ هذه المهمة لم تعُد نشطة.

• ضبط نتيجة المهمة: بعد إغلاق مهمة، يمكنك إنهاؤها من خلال ضبط نتيجتها على SUCCEEDED أو FAILED. هذا جزء مهم من إنهاء مهمة لعرض نتيجة التسليم في ميزة "مشاركة الرحلة" ولضمان إعداد الفواتير بشكل صحيح لخدمة Fleet Engine.

إغلاق مهمة

يمكنك إغلاق مهمة بإحدى الطريقتَين التاليتَين:

• تعديل حالة التوقف للمركبة : يمكنك إزالة التوقف من المركبة، ما يؤدي بدوره إلى إغلاق جميع المهام المرتبطة بالتوقف. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة تعديل حالة التوقف .
• إزالة المهمة من قائمة توقفات المركبة : يتضمّن ذلك تعديل قائمة المهام الخاصة بالتوقف، ولكن بدون أن تكون المهمة المغلقة جزءًا من القائمة. يُرجى الاطّلاع على مقالة تعديل ترتيب المهام في تعديل المهام.
• ضبط حالة المهمة على CLOSED. لا يمكن تنفيذ ذلك إلا على المهام غير المُسنَدة إلى المركبات. يعرض هذا القسم هذه الطريقة.

بعد إغلاق مهمة، لا يمكنك إعادة فتحها.

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

حقول المهام لإغلاق المهام

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

حقل مطلوب	القيمة
state	State.CLOSED

إغلاق مهمة مباشرةً

توضّح الأمثلة التالية كيفية ضبط مهمة غير مُسنَدة على حالة مغلقة، إما في gRPC أو باستخدام طلب HTTP REST إلى UpdateTask

gRPC

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String TASK_ID = "task-8241890";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Task settings
 String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
 Task task = Task.newBuilder()
   .setName(taskName)
   .setState(Task.State.CLOSED) // You can only directly CLOSE a
   .build();                    // task that is NOT assigned to a vehicle.

 // Task request
 UpdateTaskRequest updateTaskRequest =
   UpdateTaskRequest.newBuilder()  // No need for the header
       .setTask(task)
       .setUpdateMask(FieldMask.newBuilder().addPaths("state"))
       .build();

 try {
   Task updatedTask = deliveryService.updateTask(updateTaskRequest);
 } catch (StatusRuntimeException e) {
   Status s = e.getStatus();
   switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
   }
   return;
 }

REST

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state

• <id> هو معرّف فريد للمهمة.
• يجب أن يحتوي عنوان الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر خادمك <token> وفقًا للإرشادات الموضّحة في أدوار حسابات الخدمة و الرموز المميّزة الخاصة بالويب JSON.
• عليك تضمين كيان Task في نص الطلب.

مثال على أمر curl:

 # Set JWT, PROJECT_ID, and TASK_ID in the local environment
 curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "state": "CLOSED",
   "taskOutcome": "SUCCEEDED",
   "taskOutcomeTime": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
 }
 EOM

ضبط نتيجة المهمة

للإشارة إلى النتيجة الفعلية لمهمة، يمكنك ضبط النتيجة للمهام المغلقة على SUCCEEDED أو FAILED. يجب إغلاق مهمة قبل ضبط نتيجتها. لا يفرض Fleet Engine رسومًا إلا على مهام التسليم التي تكون حالتها SUCCEEDED.

تفاصيل نتيجة المهمة

تقدّم المهام أيضًا تفاصيل إضافية حول نتيجة المهمة. يمكنك ضبط هذه التفاصيل مباشرةً، وسيأخذ Fleet Engine إعداداتك في الاعتبار:

• موقع نتيجة المهمة: يملأ Fleet Engine تلقائيًا موقع نتيجة المهمة بآخر موقع جغرافي معروف للمركبة. يمكنك تقديم هذا الموقع الجغرافي بدلاً من ذلك إذا كنت تفضّل ذلك.
• وقت نتيجة المهمة: لا يملأ Fleet Engine هذا الحقل، ولكنه متاح لك لضبطه.

يمكنك استخدام أي من الطرق التالية لضبط task_outcome_location وtask_outcome_time:

• تعديلها في الطلب نفسه الذي يضبط نتيجة المهمة
• تعديلها لاحقًا، بعد ضبط نتيجة المهمة
• تعديلها مرة أخرى بعد ضبطها

يمنع Fleet Engine التعديلات التالية المتعلقة بنتائج المهام:

• لا يمكنك تعديل نتيجة مهمة بعد ضبطها على SUCCEEDED أو FAILED.
• لا يمكنك ضبط موقع نتيجة مهمة أو وقت نتيجتها للمهام التي لم يتم ضبط نتيجتها.

حقول المهام لضبط النتيجة

يوضّح هذا القسم الحقول المطلوبة والاختيارية التي يجب ضبطها عند ضبط نتيجة مهمة. يتجاهل Fleet Engine الحقول الأخرى في الكيان الخاص بالتعديل.

حقل مطلوب	القيمة
taskOutcome	Outcome.SUCCEEDED أو Outcome.FAILED

حقل اختياري	القيمة
taskOutcomeLocation	الموقع الجغرافي الذي تم فيه إكمال المهمة إذا لم يتم ضبط هذا الحقل، يضبطه Fleet Engine تلقائيًا على آخر موقع جغرافي للمركبة.
taskOutcomeTime	الطابع الزمني لوقت إكمال المهمة

أمثلة على نتائج المهام

يوضّح المثال التالي كيفية استخدام مكتبة Java gRPC وطلب HTTP REST إلى UpdateTask لضبط نتيجة مهمة على SUCCEEDED وضبط الموقع الجغرافي الذي تم فيه إكمال المهمة.

gRPC

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String TASK_ID = "task-8241890";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Task settings
 String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
 Task task = Task.newBuilder()
   .setName(taskName)
   .setTaskOutcome(TaskOutcome.SUCCEEDED)
   .setTaskOutcomeTime(now())
   .setTaskOutcomeLocation(               // Grand Indonesia East Mall
     LocationInfo.newBuilder().setPoint(
       LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
   .build();

 // Task request
 UpdateTaskRequest updateTaskRequest =
   UpdateTaskRequest.newBuilder()  // No need for the header
       .setTask(task)
       .setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
       .build();

 try {
   Task updatedTask = deliveryService.updateTask(updateTaskRequest);
 } catch (StatusRuntimeException e) {
   Status s = e.getStatus();
   switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
   }
   return;
 }

REST

PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation

• <id> هو معرّف فريد للمهمة.
• يجب أن يحتوي عنوان الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يُصدر خادمك <token> وفقًا للإرشادات الموضّحة في أدوار حسابات الخدمة و الرموز المميّزة الخاصة بالويب JSON.
• يجب أن يحتوي نص الطلب على كيان Task.

 # Set JWT, PROJECT_ID, and TASK_ID in the local environment
 curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
   -H "Content-type: application/json" \
   -H "Authorization: Bearer ${JWT}" \
   --data-binary @- << EOM
 {
   "taskOutcome": "SUCCEEDED",
   "taskOutcomeTime": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
   "taskOutcomeLocation": {
     "point": {
       "latitude": -6.195139,
       "longitude": 106.820826
     }
   }
 }
 EOM

الخطوات التالية

• العثور على المهام