חיפוש משימות

במאמר הזה מוסבר איך אפשר למצוא מידע על משימות משרת או מדפדפן. ‫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> הוא המזהה של המשימה שרוצים לחפש.
  • כותרת הבקשה חייבת להכיל שדה 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> הוא המזהה לצורכי מעקב שמשויך למשימה.

  • כותרת הבקשה צריכה להכיל את השדה 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}"

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