חיפוש משימות

במאמר הזה מוסבר איך למצוא מידע על משימות משרת או מדפדפן. ב-Fleet Engine יש שתי דרכים למצוא משימות:

  • חיפוש משימות: אתם יכולים לחפש משימות לפי המזהים הבאים:

    • מזהה המשימה: משמש משתמשים כמו מנהלי צי הרכב שיש להם גישה לתצוגה המלאה של נתוני המשימה.
    • מזהה לצורכי מעקב: משמש את תוכנת הלקוח כדי לספק מידע מוגבל למשתמש קצה, למשל מתי חבילה צפויה להגיע לביתו.

    חשוב להבין את ההבדל בין מזהה המשימה לבין מזהה לצורכי מעקב אחרי המשימה. מדובר בשני דברים שונים. אפשר לקרוא מידע נוסף בקטע שדות בסיסיים של משימות במדריך למשימות מתוזמנות.

  • הצגת רשימת משימות: גישה רחבה למשימות, שמיועדת רק למשתמשים מהימנים.

חיפוש משימות

בקטע הזה מוסבר איך לחפש משימות לפי מזהה המשימה או מזהה לצורכי מעקב. הדרישות הן:

  • חיפושים לפי מזהה לצורכי מעקב חייבים לעמוד בכללי החשיפה שמפורטים בקטע כללי חשיפה לאובייקטים במעקב.

  • כדי לצמצם את סיכוני האבטחה, השתמשו בטוקן הכי מצומצם שאפשר. לדוגמה, אם משתמשים ב-Delivery Consumer Token, כל הקריאות מחזירות רק מידע שרלוונטי לאותו משתמש קצה, כמו השולח או המקבל של המשלוח. מנוע 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;
 }

REST

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

  • ‫<id> הוא מזהה ייחודי של המשימה.
  • ‫<taskId> הוא המזהה של המשימה שרוצים לחפש.
  • ה-request header חייב להכיל את השדה 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>

  • ‫<tracking_id> הוא המזהה לצורכי מעקב שמשויך למשימה.

  • ה-request header חייב להכיל את השדה 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
טיפוסים בני מנייה (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 ולמאפיין משימה, גם באמצעות ספריית 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;
 }

REST

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

כדי להחיל מסנן על המשימות שמופיעות ברשימה, צריך לכלול פרמטר של כתובת URL מסוג filter עם שאילתת סינון עם תווי בריחה (escape) של כתובת URL בתור הערך שלו.

ה-request header חייב להכיל את השדה 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}"

המאמרים הבאים