البحث عن مهام

يوضّح هذا المستند الطرق التي يمكنك من خلالها العثور على معلومات المهام من الخادم أو المتصفّح. تتيح 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}"

إدراج المهام

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

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

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

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

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

تحجب 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 وسمة task، وذلك باستخدام كلّ من مكتبة 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}"

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