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

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

استراحت

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;
 }

استراحت

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

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

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

قدم بعدی چیست