پیدا کردن تکالیف

این سند روش‌هایی را که می‌توانید از سرور یا مرورگر اطلاعات تکلیف را پیدا کنید شرح می‌دهد. 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;
 }

استراحت

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

• <id> شناسه یکتای تکلیف است.
• <taskId> شناسه تکلیفی است که باید جستجو شود.
• سرایند درخواست باید حاوی فیلد مجوز با مقدار 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;
}

استراحت

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» استفاده کنید:

نوع فایل	قالب	مثال
مُهر زمان	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;
 }

استراحت

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

برای اعمال فیلتر روی وظایف فهرست‌شده، پارامتر نشانی وب «filter» را با پُرسمان فیلتر نشانی وب گریزدار به‌عنوان مقدار آن اضافه کنید.

سرایند درخواست باید فیلد 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}"

قدم بعدی چیست

• مدیریت ارسال‌ها