تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

البحث عن مهام

يوضّح هذا المستند الطرق التي يمكنك من خلالها العثور على معلومات المهام من الخادم أو المتصفّح. تتيح 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> هو رقم تعريف التتبع المرتبط بالمهمة.
يجب أن يحتوي رأس الطلب على الحقل Permission بقيمة 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، عليك إعادة إصدار الطلب نفسه مع الرمز المميّز للصفحة. عندما يكون الرمز المميّز للصفحة المعروضة فارغًا، لن تكون هناك المزيد من المهام متاحة للاسترجاع.

الحقول عند سرد المهام

يخفي 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 وسمة المهمة، باستخدام مكتبة gRPC في Java أو من خلال طلب 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 "الفلتر" مع قيمة طلب فلتر إلغاء عنوان URL.

يجب أن يحتوي رأس الطلب على الحقل Permission بقيمة 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}"

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

إدارة الشحنات