חיפוש משימות

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

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

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

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

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

חיפוש משימות

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

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

  • מומלץ להשתמש בטוקן הכי מצומצם שאפשר כדי להגביל את סיכוני האבטחה. לדוגמה, אם משתמשים באסימון של צרכן מסירה, כל הקריאות יחזירו רק מידע שרלוונטי למשתמש הקצה הזה, כמו השולח או הנמען של המשלוח. מערכת Fleet Engine מסירה את כל המידע האחר בתשובות. למידע נוסף על אסימונים, ראו אסימוני אינטרנט מסוג JSON.

חיפוש משימה לפי מזהה המשימה

אפשר לחפש משימה לפי מזהה המשימה בסביבת שרת באמצעות gRPC או REST. בדוגמאות הבאות מוסבר איך להשתמש בספריית 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>

  • ‎<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}"

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