Menemukan tugas

Dokumen ini menjelaskan cara menemukan informasi tugas dari server atau browser. Fleet Engine mendukung dua cara untuk menemukan tugas:

• Mencari tugas: Anda dapat mencari tugas berdasarkan ID berikut:

  • ID Tugas: digunakan oleh pengguna seperti operator armada yang memiliki akses ke tampilan lengkap data tugas.
  • ID pelacakan: digunakan oleh software klien Anda untuk memberikan informasi terbatas kepada pengguna akhir, seperti kapan paket diperkirakan akan tiba di rumah mereka.

  Pastikan Anda memahami perbedaan antara ID tugas dan ID pelacakan tugas. Padahal, dua hal tersebut tidaklah sama. Lihat Kolom tugas dasar di Panduan tugas terjadwal.

• Daftar tugas: akses luas ke tugas, hanya ditujukan untuk pengguna tepercaya.

Catatan: Jika Anda menggunakan model klien tepercaya yang memberikan kontrol kepada pengemudi atas tugas, perlu diketahui bahwa Driver SDK tidak mendukung pencarian atau daftar tugas.

Mencari tugas

Bagian ini menjelaskan cara mencari tugas berdasarkan ID tugas atau ID pelacakan. Persyaratannya adalah sebagai berikut:

• Pencarian berdasarkan ID pelacakan harus mematuhi aturan visibilitas yang dinyatakan dalam Aturan visibilitas untuk objek yang dilacak.

• Gunakan token yang paling sempit untuk membatasi risiko keamanan. Misalnya, jika Anda menggunakan Token Konsumen Pengiriman, setiap panggilan hanya akan menampilkan informasi yang relevan dengan pengguna akhir tersebut, seperti pengirim atau penerima pengiriman. Fleet Engine menyamarkan semua informasi lainnya dalam respons. Untuk informasi selengkapnya tentang token, lihat Token Web JSON.

Mencari tugas menurut ID tugas

Anda dapat mencari tugas berdasarkan ID tugasnya dari lingkungan server menggunakan gRPC atau REST. Contoh berikut menunjukkan cara menggunakan library gRPC Java atau permintaan REST ke 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> adalah ID unik untuk tugas.
• &lt;taskId&gt; adalah ID tugas yang akan dicari.
• Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> diterbitkan oleh server Anda sesuai dengan panduan yang dijelaskan dalam Service account Role dan JSON Web tokens.
• Isi permintaan harus kosong.
• Jika pencarian berhasil, isi respons akan berisi entity tugas.

Contoh perintah 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}"

Cari tugas dengan ID pelacakan

Contoh berikut menunjukkan cara mencari tugas berdasarkan ID pelacakan pengiriman menggunakan gRPC atau panggilan REST HTTP ke 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> adalah ID pelacakan yang terkait dengan tugas.

• Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> memiliki peran akun layanan yang benar. Lihat Peran akun layanan.

• Jika pencarian berhasil, isi respons akan berisi entitas taskTrackingInfo.

Contoh perintah 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}"

Membuat daftar tugas

Mencantumkan tugas meminta akses yang luas ke tugas. Tugas listingan hanya ditujukan untuk pengguna tepercaya. Gunakan token autentikasi Delivery Fleet Reader atau Admin Pengiriman saat membuat permintaan tugas daftar. Lihat Peran akun layanan untuk mengetahui informasi selengkapnya.

Memberi nomor halaman pada daftar

Daftar tugas diberi penomoran halaman. Ukuran halaman dapat ditentukan dalam permintaan tugas daftar. Jika ukuran halaman ditentukan, jumlah tugas yang ditampilkan tidak lebih besar dari ukuran halaman yang ditentukan. Jika tidak ada ukuran halaman, ukuran default yang wajar akan digunakan. Jika ukuran halaman yang diminta melebihi nilai maksimum internal, ukuran maksimum internal akan digunakan.

Daftar tugas dapat menyertakan token untuk membaca halaman hasil berikutnya. Untuk mengambil halaman berikutnya, terbitkan kembali permintaan yang sama beserta token halaman. Jika token halaman yang ditampilkan kosong, tidak ada lagi tugas yang tersedia untuk diambil.

Kolom saat mencantumkan tugas

Fleet Engine menyamarkan kolom berikut saat mencantumkan tugas:

• VehicleStop.planned_location
• VehicleStop.state
• VehicleStop.TaskInfo.taskId

Gunakan format kolom berikut berdasarkan Proposal Peningkatan Google API:

Jenis Kolom	Format	Contoh
Stempel waktu	RFC-3339	task_outcome_time = 2022-03-01T11:30:00-08:00
Durasi	Jumlah detik diikuti dengan s	task_duration = 120s
Enum	String	state = CLOSED AND type = PICKUP
Lokasi	point.latitude dan point.longitude	planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

Filter tugas yang tercantum

Anda dapat memfilter tugas yang tercantum berdasarkan sebagian besar properti tugas. Untuk sintaksis kueri filter, lihat AIP-160. Jika tidak ada kueri filter yang ditentukan, semua tugas akan dicantumkan.

Catatan: Pemfilteran pada atribut tugas dapat menyebabkan latensi pengambilan meningkat secara signifikan, dan harus digunakan dengan hati-hati.

Tabel berikut menunjukkan properti tugas yang valid yang dapat Anda gunakan untuk pemfilteran:

Properti tugas untuk memfilter daftar
type attributes tracking_id delivery_vehicle_id state planned_location	task_duration task_duration_outcome task_outcome task_outcome_location task_outcome_time

Lihat AIP-160 untuk mengetahui daftar lengkap operator kueri filter.

Contoh tugas daftar

Contoh berikut menunjukkan cara mencantumkan tugas untuk deliveryVehicleId dan atribut tugas, baik dengan library gRPC Java maupun dengan panggilan REST HTTP ke ListTasks.

Respons yang berhasil masih dapat kosong. Respons kosong menunjukkan tidak ada tugas yang terkait dengan deliveryVehicleId yang disediakan.

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

Untuk menerapkan filter ke tugas yang tercantum, sertakan parameter URL "filter" dengan kueri filter yang di-escape URL sebagai nilainya.

Header permintaan harus berisi kolom Authorization dengan nilai Bearer <token>, dengan <token> memiliki peran akun layanan yang benar. Lihat Peran akun layanan.

Pencarian yang berhasil akan memberikan isi respons dengan struktur berikut:

    // JSON representation
    {
      "tasks": [
        {
          object (Task)
        }
      ],
      "nextPageToken": string,
      "totalSize": integer
    }

Contoh perintah 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}"

Langkah berikutnya

• Mengelola pengiriman