Method: providers.vehicles.search

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

בקשת HTTP

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

כתובת ה-URL משתמשת בתחביר של Transcoding של 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)

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

משך הזמן בשניות, עם עד תשע ספרות עשרוניות, שמסתיימים ב-'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 מאפייני requiredAttributes. הערך הזה תואם למספר המאפיינים המקסימלי שמותר לכלול ברכב.
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

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

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

CurrentTripsPresent

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

טיפוסים בני מנייה (enum)
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 יכלול את הזמן שנדרש להשלמת הנסיעה הפעילה הנוכחית.

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

integer

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

integer

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

string (Timestamp format)

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

חותמת זמן בפורמט UTC 'Zulu' של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "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)

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

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

VehicleMatchType

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

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