البحث عن مهام

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

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

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

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

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

البحث عن مهام

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

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

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

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

يمكنك البحث عن مهمة من خلال معرّف المهمة من بيئة خادم باستخدام gRPC أو راحة. توضّح الأمثلة التالية كيفية استخدام مكتبة 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;
 }

راحة

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

  • &lt;id&gt; هو معرّف فريد للمهمة.
  • &lt;taskId&gt; هو رقم تعريف المهمة المطلوب البحث عنها.
  • يجب أن يحتوي عنوان الطلب على الحقل Authorize (تفويض) مع القيمة الحامل <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;
}

راحة

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

  • &lt;tracking_id&gt; هو رقم تعريف التتبع المرتبط بالمهمة.

  • يجب أن يحتوي عنوان الطلب على الحقل Authorize (تفويض) مع القيمة الحامل <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:

نوع الحقل التنسيق مثال
الطابع الزمني RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
المدة عدد الثواني متبوعًا بـ s task_duration = 120s
Enum سلسلة 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;
 }

راحة

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

لتطبيق فلتر على المهام المدرجة، يمكنك تضمين "فلتر" مَعلمة عنوان URL تتضمّن طلب بحث يتضمّن إلغاءً للوصول إلى عنوان URL كقيمة له.

يجب أن يحتوي عنوان الطلب على الحقل Authorize (تفويض) مع القيمة الحامل <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}"

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