Method: providers.vehicles.search

מחזירה רשימה של כלי רכב שתואמים לאפשרויות הבקשה.

בקשת HTTP

POST https://fleetengine.googleapis.com/v1/{parent=providers/*}/vehicles:search

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

פרמטרים של נתיב

פרמטרים
parent

string

חובה. חייב להיות בפורמט providers/{provider}. הספק צריך להיות מזהה הפרויקט (לדוגמה, sample-cloud-project) של הפרויקט ב-Google Cloud שאליו משויך חשבון השירות שמבצע את הקריאה הזו.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "header": {
    object (RequestHeader)
  },
  "pickupPoint": {
    object (TerminalLocation)
  },
  "dropoffPoint": {
    object (TerminalLocation)
  },
  "pickupRadiusMeters": integer,
  "count": integer,
  "minimumCapacity": integer,
  "tripTypes": [
    enum (TripType)
  ],
  "maximumStaleness": string,
  "vehicleTypes": [
    {
      object (VehicleType)
    }
  ],
  "requiredAttributes": [
    {
      object (VehicleAttribute)
    }
  ],
  "requiredOneOfAttributes": [
    {
      object (VehicleAttributeList)
    }
  ],
  "requiredOneOfAttributeSets": [
    {
      object (VehicleAttributeList)
    }
  ],
  "orderBy": enum (VehicleMatchOrder),
  "includeBackToBack": boolean,
  "tripId": string,
  "currentTripsPresent": enum (CurrentTripsPresent),
  "filter": string
}
שדות
header

object (RequestHeader)

כותרת הבקשה הרגילה של Fleet Engine.
pickupPoint

object (TerminalLocation)

חובה. נקודת האיסוף שצריך לחפש בה.
dropoffPoint

object (TerminalLocation)

המיקום המיועד למסירת הלקוח. חובה למלא את השדה הזה אם השדה tripTypes מכיל את הערך TripType.SHARED.
pickupRadiusMeters

integer

חובה. ההגדרה הזו מגדירה את רדיוס חיפוש הרכב סביב נקודת האיסוף. יוחזרו רק כלי רכב שנמצאים ברדיוס החיפוש. הערך חייב להיות בין 400 ל-10,000 מטר (כולל).
count

integer

חובה. מציין את המספר המקסימלי של רכבים שיש להחזיר. הערך חייב להיות בין 1 ל-50 (כולל).
minimumCapacity

integer

חובה. מציין את מספר הנוסעים שרוצים לקחת בחשבון בנסיעה. הערך חייב להיות לפחות 1. ערך הקיבולת של הנהג לא נלקח בחשבון.
tripTypes[]

enum (TripType)

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

string (Duration format)

מגביל את החיפוש רק לכלי הרכב ששלחו עדכוני מיקום ל-Feet Engine במהלך פרק הזמן שצוין. רכבים נייחים שעדיין משדרים את המיקומים שלהם לא נחשבים למיושנים. אם שדה זה לא מוגדר, השרת ישתמש בחמש דקות כערך ברירת המחדל.

משך זמן בשניות עם עד תשע ספרות עשרוניות, המסתיים ב-'s'. דוגמה: "3.5s".
vehicleTypes[]

object (VehicleType)

חובה. מגביל את החיפוש לרכבים עם אחד מהסוגים שצוינו. צריך לציין לפחות סוג אחד של רכב. אסור להשתמש בסוגי רכב עם הקטגוריה UNKNOWN.
requiredAttributes[]

object (VehicleAttribute)

מתקשרים יכולים ליצור פעולות לוגיות מורכבות באמצעות כל שילוב של השדות requiredAttributes, requiredOneOfAttributes ו-requiredOneOfAttributeSets.

requiredAttributes היא רשימה; requiredOneOfAttributes משתמש בהודעה שמאפשרת ליצור רשימה של רשימות. בשילוב, שני השדות מאפשרים את הרכבה של הביטוי הזה:

(requiredAttributes[0] AND requiredAttributes[1] AND ...)
AND
(requiredOneOfAttributes[0][0] OR requiredOneOfAttributes[0][1] OR
...)
AND
(requiredOneOfAttributes[1][0] OR requiredOneOfAttributes[1][1] OR
...)

החיפוש יוגבל רק לכלי רכב עם המאפיינים שצוינו. השדה הזה הוא פעולת חיבור/AND. אפשר להוסיף עד 50 מאפיינים נדרשים. הערך הזה תואם למספר המקסימלי של מאפיינים שמותר להוסיף לרכב.
requiredOneOfAttributes[]

object (VehicleAttributeList)

החיפוש יוגבל רק לכלי רכב שיש בהם לפחות אחד מהמאפיינים שצוינו בכל VehicleAttributeList. בכל רשימה, הרכב צריך להתאים לפחות לאחד מהמאפיינים. השדה הזה הוא פעולת חיתוך/OR כוללת בכל VehicleAttributeList, ופעולת חיבור/AND בכל האוסף של VehicleAttributeList.
requiredOneOfAttributeSets[]

object (VehicleAttributeList)

requiredOneOfAttributeSets מספק פונקציונליות נוספת.

בדומה ל-requiredOneOfAttributes, requiredOneOfAttributeSets משתמש בהודעה שמאפשרת ליצור רשימה של רשימות, וכך מתאפשרת ביטויים כמו זה:

(requiredAttributes[0] AND requiredAttributes[1] AND ...)
AND
(
  (requiredOneOfAttributeSets[0][0] AND
  requiredOneOfAttributeSets[0][1] AND
  ...)
  OR
  (requiredOneOfAttributeSets[1][0] AND
  requiredOneOfAttributeSets[1][1] AND
  ...)
)

החיפוש יוגבל רק לרכבים עם כל המאפיינים שמסומנים במאפיין VehicleAttributeList. בכל רשימה, הרכב חייב להתאים לכל המאפיינים. השדה הזה הוא פעולת חיבור/AND בכל VehicleAttributeList ופעולת ניתוק/OR כוללת באוסף של VehicleAttributeList.
orderBy

enum (VehicleMatchOrder)

חובה. מציין את קריטריון הסדר הרצוי של התוצאות.
includeBackToBack

boolean

הערך הזה מציין אם כלי רכב עם נסיעה פעילה אחת עומדים בדרישות לחיפוש הזה. השדה הזה משמש רק אם לא צוין currentTripsPresent. אם לא צוין currentTripsPresent והשדה הזה הוא false, רכבים עם נסיעות שהוקצו לא ייכללו בתוצאות החיפוש. אם לא צוין currentTripsPresent והשדה הזה הוא true, תוצאות החיפוש יכולות לכלול רכבים עם נסיעה פעילה אחת בסטטוס ENROUTE_TO_DROPOFF. אם מציינים currentTripsPresent, אי אפשר להגדיר את השדה הזה כ-True.

ערך ברירת המחדל הוא false.
tripId

string

ציון הנסיעה המשויכת אל SearchVehicleRequest.
currentTripsPresent

enum (CurrentTripsPresent)

הכיתוב הזה מציין אם כלי רכב עם נסיעות פעילות עומדים בדרישות לחיפוש הזה. חובה להגדיר את הערך הזה לערך שאינו CURRENT_TRIPS_PRESENT_UNSPECIFIED אם tripType כולל SHARED.
filter

string

זה שינוי אופציונלי. שאילתת סינון שצריך להחיל כשמחפשים רכבים. בכתובת http://aip.dev/160 אפשר לראות דוגמאות לתחביר של המסנן.

השדה הזה נועד להחליף את השדות requiredAttributes, requiredOneOfAttributes ו-required_one_of_attributes_sets. אם מצוין כאן ערך שאינו ריק, השדות הבאים חייבים להיות ריקים: requiredAttributes, requiredOneOfAttributes ו-required_one_of_attributes_sets.

המסנן הזה פועל כסעיף AND עם אילוצים אחרים, כמו minimumCapacity או vehicleTypes.

חשוב לשים לב שהשאילתות היחידות שנתמכות הן בנושא מאפייני רכב (לדוגמה, attributes.<key> = <value> או attributes.<key1> = <value1> AND attributes.<key2> = <value2>). מספר ההגבלות המקסימלי שמותר בשאילתת סינון הוא 50.

בנוסף, כל המאפיינים נשמרים כמחרוזות, כך שההשוואות היחידות שנתמכות מול מאפיינים הן השוואות מחרוזות. כדי לבצע השוואה מול מספר או ערכים בוליאניים, צריך להקיף את הערכים במירכאות מפורשות, כך שהמערכת תתייחס אליהם כמחרוזות (לדוגמה, attributes.<key> = "10" או attributes.<key> = "true").

גוף התשובה

הודעת תגובה אחת (vehicles.search).

אם הפעולה בוצעה ללא שגיאות, גוף התשובה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "matches": [
    {
      object (VehicleMatch)
    }
  ]
}
שדות
matches[]

object (VehicleMatch)

רשימה של רכבים שתואמים לקריטריונים של SearchVehiclesRequest, מסודרים לפי השדה SearchVehiclesRequest.order_by.

VehicleAttributeList

סוג נתונים של רשימת רשימות למאפייני רכב.

ייצוג JSON 
{
  "attributes": [
    {
      object (VehicleAttribute)
    }
  ]
}
שדות
attributes[]

object (VehicleAttribute)

רשימת המאפיינים באוסף הזה.

VehicleMatchOrder

מציין את סדר ההתאמות של הרכב בתשובה.

טיפוסים בני מנייה (enums)
UNKNOWN_VEHICLE_MATCH_ORDER ברירת המחדל, משמשת להזמנה של התאמת רכבים שלא צוינה או לא מזוהה.
PICKUP_POINT_ETA בסדר עולה לפי זמן הנסיעה של הרכב אל נקודת האיסוף.
PICKUP_POINT_DISTANCE סדר עולה לפי מרחק הנסיעה של כלי הרכב אל נקודת האיסוף.
DROPOFF_POINT_ETA סדר עולה לפי זמן הנסיעה של כלי הרכב אל נקודת ההורדה. אפשר להשתמש בהזמנה הזו רק אם נקודת ההורדה צוינה בבקשה.
PICKUP_POINT_STRAIGHT_DISTANCE סדר עולה לפי המרחק בקו הישר מהמיקום האחרון שדווח ברכב עד לנקודת האיסוף.
COST סדר עולה לפי עלות ההתאמה שהוגדרה. עלות ההתאמה מוגדרת כחישוב משוקלל בין המרחק בקו ישר לבין זמן ההגעה המשוער. המשקלים מוגדרים עם ערכי ברירת מחדל ואפשר לשנות אותם לפי לקוח. אם צריך לשנות את המשקולות האלה בפרויקט, יש לפנות לתמיכה של Google.

CurrentTripsPresent

ההגדרה הזו מציינת את סוגי ההגבלות על הנסיעות הנוכחיות של הרכב.

טיפוסים בני מנייה (enums)
CURRENT_TRIPS_PRESENT_UNSPECIFIED הזמינות של כלי רכב שיש בהם נסיעות נקבעת לפי השדה includeBackToBack.
NONE כלי רכב ללא נסיעות יכולים להופיע בתוצאות החיפוש. כשמשתמשים בערך הזה, includeBackToBack לא יכול להיות true.
ANY כלי רכב עם 5 נסיעות עדכניות ו-10 ציוני דרך לכל היותר נכללים בתוצאות החיפוש. כשמשתמשים בערך הזה, includeBackToBack לא יכול להיות true.

VehicleMatch

מכילה את הרכב ואומדנים קשורים לרכב שתואמים לנקודות הנסיעות הפעילות ברכב SearchVehiclesRequest.

ייצוג JSON 
{
  "vehicle": {
    object (Vehicle)
  },
  "vehiclePickupEta": string,
  "vehiclePickupDistanceMeters": integer,
  "vehiclePickupStraightLineDistanceMeters": integer,
  "vehicleDropoffEta": string,
  "vehiclePickupToDropoffDistanceMeters": integer,
  "tripType": enum (TripType),
  "vehicleTripsWaypoints": [
    {
      object (Waypoint)
    }
  ],
  "vehicleMatchType": enum (VehicleMatchType),
  "requestedOrderedBy": enum (VehicleMatchOrder),
  "orderedBy": enum (VehicleMatchOrder)
}
שדות
vehicle

object (Vehicle)

חובה. רכב שתואם לבקשה.
vehiclePickupEta

string (Timestamp format)

זמן ההגעה המשוער של הרכב לנקודת האיסוף שצוינה בבקשה. ערך ריק מציין כישלון בחישוב זמן ההגעה המשוער של הרכב. אם הערך של SearchVehiclesRequest.include_back_to_back היה true וברכב הזה יש נסיעה פעילה, vehiclePickupEta כולל את הזמן שנדרש להשלמת הנסיעה הפעילה הנוכחית.

חותמת זמן בפורמט "זולו" RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
vehiclePickupDistanceMeters

integer

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

integer

חובה. המרחק הישר בין הרכב לנקודת האיסוף שצוין בבקשה.
vehicleDropoffEta

string (Timestamp format)

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

חותמת זמן בפורמט "זולו" RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
vehiclePickupToDropoffDistanceMeters

integer

מרחק הנסיעה של הרכב (במטרים) מנקודת האיסוף אל נקודת ההורדה שצוינה בבקשה. המרחק הוא רק בין שתי הנקודות, והוא לא כולל את מיקום הרכב או נקודות אחרות שצריך לבקר בהן לפני שהרכב מגיע לנקודת האיסוף או לנקודת ההורדה. הערך יאוכלס רק כאשר יצוינו dropoffPoint בבקשה. ערך ריק מציין כשל בחישוב המרחק מנקודת האיסוף עד לנקודת ההורדה שצוינה בבקשה.
tripType

enum (TripType)

חובה. סוג הנסיעה לפי הבקשה ששימשה לחישוב זמן ההגעה המשוער לנקודת האיסוף.
vehicleTripsWaypoints[]

object (Waypoint)

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

enum (VehicleMatchType)

סוג ההתאמה של הרכב.
requestedOrderedBy

enum (VehicleMatchOrder)

הסדר המבוקש למיון התאמות כלי רכב.
orderedBy

enum (VehicleMatchOrder)

ההזמנה בפועל שבה נעשה שימוש ברכב הזה. בדרך כלל הערך הזה יתאים לשדה 'orderBy' מהבקשה; עם זאת, בנסיבות מסוימות כמו שגיאת שרת פנימית, ניתן להשתמש בשיטה אחרת (כמו PICKUP_POINT_STRAIGHT_DISTANCE).

נקודת ציון

מתאר נקודות ביניים לאורך מסלול של VehicleMatch בSearchVehiclesResponse. הקונספט הזה מיוצג בתור TripWaypoint בכל נקודות הקצה האחרות.

ייצוג JSON 
{
  "latLng": {
    object (LatLng)
  },
  "eta": string
}
שדות
latLng

object (LatLng)

המיקום של ציון הדרך הזה.
eta

string (Timestamp format)

הזמן המשוער שהרכב יגיע לנקודת הדרך הזו.

חותמת זמן בפורמט "זולו" RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".

VehicleMatchType

סוג ההתאמה לרכב.

טיפוסים בני מנייה (enums)
UNKNOWN סוג התאמה לא ידוע של רכב
EXCLUSIVE כרגע לא הוקצתה נסיעה לרכב, והוא יכול להמשיך לנקודת האיסוף.
BACK_TO_BACK הרכב מוקצה כרגע לנסיעה, אבל הוא יכול להמשיך לנקודת האיסוף אחרי השלמת הנסיעה. בחישובי זמן ההגעה המשוער והמרחק, הנסיעה הנוכחית נלקחת בחשבון.
CARPOOL יש ברכב מספיק קיבולת לנסיעה משותפת.
CARPOOL_BACK_TO_BACK הרכב יסיים את הנסיעה הפעילה הנוכחית לפני שימשיך לנקודת האיסוף. בחישובי זמן ההגעה המשוער והמרחק, הנסיעה הנוכחית נלקחת בחשבון.