البحث عن مهام

يصف هذا المستند الطرق التي يمكنك من خلالها العثور على معلومات المهام من خادم أو متصفح. تتيح Fleet Engine طريقتَين للعثور على المهام:

  • البحث عن المهام: يمكنك البحث عن المهام باستخدام أرقام التعريف التالية:

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

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

  • قائمة المهام: إذن وصول واسع النطاق إلى المهام، مخصّص للمستخدمين الموثوق بهم فقط.

البحث عن المهام

يصف هذا القسم كيفية البحث عن المهام حسب رقم تعريف المهمة أو رقم تعريف التتبُّع. ويجب استيفاء المتطلبات التالية:

  • يجب أن تلتزم عمليات البحث حسب رقم تعريف التتبُّع بقواعد مستوى العرض الموضّحة في قواعد مستوى العرض للعناصر التي يتم تتبُّعها.

  • استخدِم الرمز المميز الأضيق نطاقًا قدر الإمكان للحدّ من المخاطر الأمنية. على سبيل المثال، إذا كنت تستخدم رمزًا مميزًا خاصًا بمستهلك خدمة التوصيل، ستعرض أي طلبات معلومات ذات صلة بالمستخدم النهائي فقط، مثل المرسل أو المستلم للشحنة. تحذف Fleet Engine جميع المعلومات الأخرى في الردود. لمزيد من المعلومات حول الرموز المميّزة، يُرجى الاطّلاع على رموز JSON المميّزة للويب.

البحث عن مهمة حسب معرّف المهمة

يمكنك البحث عن مهمة باستخدام رقم تعريفها من بيئة خادم باستخدام gRPC أو REST. توضّح الأمثلة التالية كيفية استخدام مكتبة Java gRPC أو طلب REST إلى GetTask.

gRPC

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

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Task request
 String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
 GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
     .setName(taskName)
     .build();

 try {
   Task task = deliveryService.getTask(getTaskRequest);
 } catch (StatusRuntimeException e) {
   Status s = e.getStatus();
   switch (s.getCode()) {
      case NOT_FOUND:
        break;

      case PERMISSION_DENIED:
        break;
   }
   return;
 }

REST

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>

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

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

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

البحث عن المهام حسب رقم تعريف التتبّع

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

gRPC

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setTrackingId(TRACKING_ID)
    .build();

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>

  • ‫<tracking_id> هو رقم تعريف التتبّع المرتبط بالمهمة.

  • يجب أن يحتوي عنوان الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يحمل <token> دور حساب الخدمة الصحيح. يُرجى الاطّلاع على أدوار حساب الخدمة.

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

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

# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"

عرض المهام

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

تقسيم القوائم إلى صفحات

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

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

الحقول عند إدراج المهام

يحجب Fleet Engine الحقول التالية عند عرض المهام:

  • VehicleStop.planned_location
  • VehicleStop.state
  • VehicleStop.TaskInfo.taskId

استخدِم تنسيقات الحقول التالية استنادًا إلى "اقتراحات تحسين واجهات Google API":

نوع الحقل التنسيق مثال
الطابع الزمني RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
المدة عدد الثواني متبوعًا بـ s task_duration = 120s
تعداد سلسلة state = CLOSED AND type = PICKUP
الموقع الجغرافي point.latitude وpoint.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

فلترة المهام المُدرَجة

يمكنك فلترة المهام المدرَجة حسب معظم سمات المهام. لمعرفة بنية طلب البحث الخاص بالفلتر، يُرجى الاطّلاع على AIP-160. في حال عدم تحديد طلب بحث الفلتر، يتم إدراج جميع المهام.

يعرض الجدول التالي سمات المهام الصالحة التي يمكنك استخدامها للفلترة:

خصائص المهام لفلترة القوائم
  • type
  • attributes
  • tracking_id
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_duration_outcome
  • task_outcome
  • task_outcome_location
  • task_outcome_time

يمكنك الاطّلاع على AIP-160 للحصول على قائمة كاملة بعوامل تشغيل طلبات البحث عن الفلاتر.

أمثلة على مهام القوائم

يوضّح المثال التالي كيفية عرض قائمة بالمهام لسمة deliveryVehicleId وسمة مهمة، باستخدام مكتبة Java gRPC وطلب HTTP REST إلى ListTasks.

يمكن أن يظل الرد الناجح فارغًا. يشير الردّ الفارغ إلى عدم توفّر أي مهام مرتبطة بـ deliveryVehicleId المقدَّم.

gRPC

 static final String PROJECT_ID = "my-delivery-co-gcp-project";
 static final String TRACKING_ID = "TID-7449w087464x5";

 DeliveryServiceBlockingStub deliveryService =
   DeliveryServiceGrpc.newBlockingStub(channel);

 // Tasks request
 String parent = "providers/" + PROJECT_ID;
 ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder()  // No need for the header
     .setParent(parent)
     .setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
     .build();

 try {
   ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
 } catch (StatusRuntimeException e) {
   Status s = e.getStatus();
   switch (s.getCode()) {
      case NOT_FOUND:
        break;

      case PERMISSION_DENIED:
        break;
   }
   return;
 }

REST

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks

لتطبيق فلتر على المهام المدرَجة، أدرِج مَعلمة عنوان URL "filter" مع طلب بحث فلتر تم تجاوزه في عنوان URL كقيمة له.

يجب أن يحتوي عنوان الطلب على حقل Authorization بالقيمة Bearer <token>، حيث يحمل <token> الدور الصحيح لحساب الخدمة. اطّلِع على أدوار حساب الخدمة.

يوفّر البحث الناجح نص استجابة بالبنية التالية:

    // JSON representation
    {
      "tasks": [
        {
          object (Task)
        }
      ],
      "nextPageToken": string,
      "totalSize": integer
    }

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

 # Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
 curl -H "Authorization: Bearer ${JWT}" \
   "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

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