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)

מגביל את החיפוש רק לכלי רכב ששלחו עדכוני מיקום ל-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 מאפייני חובה. הערך הזה תואם למספר המאפיינים המקסימלי שמותר לכלול ברכב.
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 פרטנית/או כוללת בכל האוסף של 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 יכלול את הזמן שנדרש להשלמת הנסיעה הפעילה הנוכחית.

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

integer

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

integer

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

string (Timestamp format)

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

חותמת זמן ב-RFC3339 UTC 'Zulu' בפורמט של רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "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 'Zulu' בפורמט של רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".

VehicleMatchType

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

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