ค้นหางาน

เอกสารนี้อธิบายวิธีที่คุณจะค้นหาข้อมูลงานจาก เซิร์ฟเวอร์หรือเบราว์เซอร์ Fleet Engine รองรับการค้นหางาน 2 วิธีดังนี้

  • ค้นหางาน: คุณสามารถค้นหางานโดยใช้รหัสต่อไปนี้

    • รหัสงาน: ใช้โดยผู้ใช้ เช่น ผู้ให้บริการกลุ่มยานพาหนะที่มีสิทธิ์เข้าถึง มุมมองข้อมูลงาน
    • รหัสติดตาม: ใช้โดยซอฟต์แวร์ไคลเอ็นต์เพื่อให้ข้อมูลที่จำกัด ไปยังผู้ใช้ปลายทาง เช่น เมื่อคาดว่าจะมีพัสดุที่บ้าน

    อย่าลืมทำความเข้าใจความแตกต่างระหว่างรหัสงานและงาน รหัสติดตาม สองรายการนี้ไม่เหมือนกัน โปรดดูช่องงานพื้นฐานใน คำแนะนำสำหรับงานที่กำหนดเวลาไว้

  • แสดงรายการงาน: การเข้าถึงงานแบบกว้าง มีไว้สำหรับผู้ใช้ที่เชื่อถือได้เท่านั้น

ค้นหางาน

ส่วนนี้จะอธิบายวิธีค้นหางานตามรหัสงานหรือรหัสติดตาม มี ข้อกำหนดต่อไปนี้

  • การค้นหาด้วยรหัสติดตามต้องเป็นไปตามกฎระดับการเข้าถึง ระบุไว้ในกฎระดับการเข้าถึงสำหรับออบเจ็กต์ที่ติดตาม

  • ใช้โทเค็นที่แคบที่สุดเท่าที่ทำได้เพื่อจำกัดความเสี่ยงด้านความปลอดภัย ตัวอย่างเช่น หากคุณ ใช้ Delivery Consumer Token ในการส่งคืนการเรียกทั้งหมด เฉพาะข้อมูลที่เกี่ยวข้องกับผู้ใช้ปลายทาง เช่น ผู้จัดส่งหรือ เป็นผู้รับพัสดุ Fleet Engine จะปกปิดข้อมูลอื่นๆ ทั้งหมดใน คำตอบ โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับโทเค็นที่หัวข้อโทเค็นเว็บ JSON

ค้นหางานตามรหัสงาน

คุณค้นหางานด้วยรหัสงานจากสภาพแวดล้อมของเซิร์ฟเวอร์ได้โดยใช้ gRPC หรือ พัก ตัวอย่างต่อไปนี้แสดงวิธีใช้ไลบรารี gRPC ของ Java หรือ คำขอ 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>

  • &lt;id&gt; เป็นตัวระบุที่ไม่ซ้ำสำหรับงาน
  • &lt;taskId&gt; คือรหัสของงานที่จะค้นหา
  • ส่วนหัวของคำขอต้องมีช่อง 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>

  • &lt;tracking_id&gt; คือรหัสติดตามที่เชื่อมโยงกับงาน

  • ส่วนหัวของคำขอต้องมีช่อง 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}"

แสดงรายการงาน

งานในรายการจะขอสิทธิ์เข้าถึงงานแบบกว้าง งานแสดงรายการมีไว้เพื่อ ผู้ใช้ที่เชื่อถือได้ ใช้โทเค็นการตรวจสอบสิทธิ์ Delivery Fleet Reader หรือ Delivery Admin เมื่อสร้างรายการคำของาน โปรดดูข้อมูลเพิ่มเติมในบทบาทของบัญชีบริการ

รายการเลขหน้า

มีการแบ่งหน้ารายการงานแล้ว ขนาดหน้าเว็บสามารถระบุในคำของานรายการได้ หากระบุขนาดหน้า จำนวนงานที่ส่งคืนจะไม่มากกว่า ใหญ่กว่าขนาดหน้าที่ระบุ หากไม่มีขนาดหน้า จะใช้ค่าเริ่มต้นที่สมเหตุสมผล หากขนาดหน้าที่ขอเกินค่าสูงสุดภายใน จากนั้นจะใช้ค่าสูงสุดภายใน

รายการงานอาจมีโทเค็นสำหรับอ่านผลการค้นหาหน้าถัดไปได้ ถึง เรียกหน้าถัดไปนั้น ออกคำขอเดิมอีกครั้งพร้อมกับโทเค็นของหน้าเว็บ เมื่อโทเค็นหน้าเว็บที่ส่งกลับว่างเปล่า คุณจะไม่เห็นงานเพิ่มเติม การดึงข้อมูล

ช่องเมื่อแสดงรายการงาน

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 ที่มีการค้นหาตัวกรองที่ใช้ Escape กับ 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}"

ขั้นตอนถัดไป