חיפוש משימות

במאמר הזה מוסבר איך אפשר למצוא מידע על משימות משרת או מדפדפן. ב-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;
 }

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 עם שאילתת מסנן שבוצעה בה החלפת תווים בכתובת 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}"

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