ממשק ה-API של Fleet Engine ליצירת נסיעות ולמשלוחים על פי דרישה מאפשר לנהל נסיעות ואת מצב הרכב באפליקציות שלך ל'נסיעה' ו'התקדמות הזמנה'. הוא מטפל בעסקאות בין Driver SDK, ה-SDK לצרכן שירות לקצה העורפי – שיכול לתקשר עם Fleet Engine באמצעות ב-gRPC או קריאות REST.
דרישות מוקדמות
לצורכי פיתוח, צריך להתקין את הענן ב-SDK (gcloud) ומאומתים בפרויקט שלכם.
מעטפת
gcloud auth login
אתם אמורים לראות הודעה כמו:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
חשוב לוודא שממשקי ה-API של Fleet Engine בפתרונות Fleet Engine הם על פי דרישה.
מעטפת
gcloud --project=project-id services enable fleetengine.googleapis.com
אם הפקודה הזו מובילה לשגיאה, יש לפנות לאדמין של הפרויקט. ונציג התמיכה של Google כדי לקבל גישה.
רישום ביומן
שירות Fleet Engine יכול לכתוב הודעות ביומן על קריאות ל-API שהוא מקבל ל יומנים של Google Cloud Platform. אפשר לקרוא מידע נוסף במסמכי התיעוד של Cloud Logging. סקירה כללית של אופן הקריאה והניתוח של יומנים.
ייתכן שהרישום ביומן לא מופעל כברירת מחדל עבור פרויקטים שנוצרו לפני 10 בפברואר 2022. לצפייה תיעוד הרישום ביומן אפשר לקבל פרטים נוספים.
ספריות לקוח
אנחנו מפרסמים ספריות לקוח בכמה שפות תכנות נפוצות. האלה ספריות יעזרו לספק חוויית מפתח טובה יותר בהשוואה ל-REST או ל-gRPC. כדי לקבל הוראות לקבלת ספריות לקוח לאפליקציית השרת שלכם, לראות ספריות לקוח.
בדוגמאות של Java בתיעוד הזה, ההנחה היא שיש לכם היכרות עם gRPC.
אימות והרשאה
אפשר להגדיר את היכולות שמסופקות על ידי 'נסיעה' ו'התקדמות ההזמנה' באמצעות מסוף Google Cloud. ממשקי ה-API וערכות ה-SDK האלה מחייבים שימוש באסימוני אינטרנט מסוג JSON נחתמו באמצעות חשבונות שירות שנוצרו מתוך מסוף Cloud.
הגדרת פרויקט בענן
כדי להגדיר את הפרויקט בענן, קודם צריך ליצור את הפרויקט ואז ליצור חשבונות שירות.
כדי ליצור את הפרויקט ב-Google Cloud:
- יוצרים פרויקט ב-Google Cloud באמצעות מסוף Google Cloud.
- באמצעות מרכז השליטה של ממשקי ה-API והשירותים, הפעל את API מקומי של נסיעות ומשלוחים.
לחשבונות השירות משויכים תפקיד אחד או יותר. הם משמשים ליצירה אסימוני אינטרנט JSON שמעניקים קבוצות הרשאות שונות בהתאם תפקידים. בדרך כלל, כדי להפחית את הסיכון לניצול לרעה, ניתן ליצור מספר חשבונות שירות, שכל אחד מהם כולל את קבוצת התפקידים המינימלית הנדרשת.
'התקדמות נסיעה' ו'התקדמות ההזמנה' משתמשים בתפקידים הבאים:
תפקיד | תיאור |
---|---|
משתמש SDK לצרכנים ב-Fleet Engine
roles/fleetengine.consumerSdkUser |
התפקיד הזה מאפשר לחפש כלי רכב ולאחזר מידע על כלי רכב ונסיעות. אסימונים שנוצרו על ידי חשבון שירות באמצעות בדרך כלל משתמשים בהם ממכשירים ניידים שפועלים באפליקציות לשיתוף נסיעות או למשלוחים. |
משתמש ב-Fleet Engine Driver SDK
roles/fleetengine.driverSdkUser |
מעניק הרשאה לעדכן מיקומים ומסלולים של רכבים כדי לאחזר מידע על כלי רכב ונסיעות. האסימונים נוצרו חשבון שירות עם התפקיד הזה בדרך כלל משמש מכשירים ניידים עם אפליקציית נהגי שיתוף נסיעות או משלוחים. |
אדמין על פי דרישה של Fleet Engine
roles/fleetengine.ondemandAdmin |
התפקיד הזה מאפשר לקרוא ולכתוב את כל מקורות המידע לגבי רכבים ונסיעות. חשבונות משתמשים עם התפקיד הזה לא צריכים להשתמש באסימוני JWT, ועליהם להשתמש במקום זאת משתמשים ב-Application Default Credentials המערכת מתעלמת מהצהרות JWT מותאמות אישית. יש להגביל את התפקיד הזה לסביבות מהימנות (הקצה העורפי של הלקוח). |
roles/fleetengine.serviceSuperUser |
התפקיד הזה מאפשר לכל ממשקי ה-API של כלי הרכב והנסיעות. אסימונים שהוטבעו
על ידי חשבון שירות עם התפקיד הזה, בדרך כלל משמש מהקצה העורפי שלך
שרתים. התפקיד הזה הוצא משימוש. העדפה
יש גם אפשרות roles/fleetengine.ondemandAdmin . |
לדוגמה, ליצור חשבון שירות לכל אחד משלושת התפקידים ולהקצות את התפקידים המתאימים
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
ערכות ה-SDK לנהגים ולצרכנים מבוססות על התפקידים הרגילים האלה.
לחלופין, אפשר ליצור תפקידים בהתאמה אישית שמאפשרים קבוצה שרירותית של הרשאות שיקובצו יחד. בערכות ה-SDK לנהג ולצרכן יוצגו הודעות שגיאה בכל פעם חסרה ההרשאה הנדרשת. לכן, אנחנו ממליצים מאוד באמצעות קבוצת התפקידים הרגילה שמוצגת למעלה, בלי להשתמש בתפקידים בהתאמה אישית.
מטעמי נוחות, אם אתם צריכים ליצור אסימוני JWT עבור לקוחות לא מהימנים, ניתן להוסיף משתמשים בתפקיד 'יצירת אסימונים בחשבון שירות', מאפשרים להם ליצור אסימונים באמצעות כלי שורת הפקודה של gcloud.
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
כאשר my-user@example.com
הוא האימייל המשמש
ביצוע אימות באמצעות gcloud (gcloud auth list
--format='value(account)'
).
ספריית אימות של Fleet Engine
ב-Fleet Engine משתמשים באסימוני JWT (JSON Web Tokens) כדי להגביל את הגישה אל ממשקי API של Fleet Engine. הספרייה החדשה של Fleet Engine Auth, זמין ב-GitHub, מפשטת את בניית אסימוני JWT של Fleet Engine וחותמת עליהם באופן מאובטח.
הספרייה מספקת את היתרונות הבאים:
- מפשט את תהליך היצירה של אסימוני Fleet Engine.
- מספקת מנגנוני חתימת אסימונים שאינם שימוש בקובצי פרטי כניסה (כמו התחזות לחשבון שירות).
- מצרף אסימונים חתומים לבקשות יוצאות שנשלחות מ-stub של gRPC או לקוח GAPIC.
יצירת אסימון רשת מבוסס JSON (JWT) להרשאה
כשלא משתמשים בספריית Fleet Engine Auth, אסימוני JWT (JSON Web Tokens) צריכים שנוצר ישירות ב-codebase שלכם. לשם כך צריך להיות לכם גם להבין את אסימוני ה-JWT ואיך הם קשורים ל-Fleet Engine. לכן אנחנו מומלץ מאוד להשתמש בספריית Fleet Engine Auth.
בתוך Fleet Engine, אסימוני אינטרנט JSON (JWT) מספקים אימות לטווח קצר ולוודא שמכשירים יכולים לשנות רק כלי רכב, נסיעות או משימות עבור שהם מורשים. אסימוני JWT מכילים כותרת וקטע הצהרה על זכויות יוצרים. קטע הכותרת מכיל מידע כמו מפתח פרטי לשימוש (המתקבל מחשבונות שירות) וההצפנה באלגוריתם כלשהו. הקטע של התלונה מכיל מידע כמו זמן היצירה של האסימון, זמן החיים של האסימונים, השירותים טענה לגישה אל, ומידע אחר על הרשאה לצורך צמצום היקף גישה; למשל, מזהה הרכב.
מקטע כותרת JWT מכיל את השדות הבאים:
שדה | תיאור |
---|---|
אלג | האלגוריתם שבו צריך להשתמש. 'RS256'. |
הקלדה | סוג האסימון. JWT. |
ילד | מזהה המפתח הפרטי של חשבון השירות שלכם. אפשר למצוא את הערך הזה בשדה 'private_key_id' בקובץ ה-JSON של חשבון השירות. צריך להקפיד להשתמש במפתח מחשבון שירות עם רמת ההרשאות המתאימה. |
קטע של הצהרות JWT מכיל את השדות הבאים:
שדה | תיאור |
---|---|
iss | כתובת האימייל של חשבון השירות שלכם. |
sub | כתובת האימייל של חשבון השירות שלכם. |
אוד | SERVICE_NAME של חשבון השירות שלך, במקרה הזה https://fleetengine.googleapis.com/ |
iat | חותמת הזמן של מועד יצירת האסימון, צוינה בשניות שחלפו מ-00:00:00 UTC, 1 בינואר 1970. ממתינים 10 דקות להטיה. אם המועד של חותמת הזמן רחוק מדי בעבר. אחרת, השרת עשוי לדווח על שגיאה. |
ניסיון | חותמת הזמן של זמן התפוגה של האסימון, מצוינת בשניות שחלפו מ-00:00:00 UTC, 1 בינואר 1970. הבקשה תיכשל אם חותמת הזמן בעוד יותר משעה. |
הרשאה | בהתאם לתרחיש לדוגמה, יכול להיות שהמאפיין 'vehicleid' או 'tripid'. |
יצירת אסימון JWT פירושה חתימה עליו. להוראות ולדוגמאות קוד ליצירה ולחתימה של ה-JWT. תוכלו לקרוא הרשאה לחשבון שירות ללא OAuth. לאחר מכן אפשר לצרף אסימון חתום לקריאות ל-gRPC או לשיטות אחרות שבהן נעשה שימוש כדי לגשת ל-Fleet Engine.
הצהרות JWT
כשיוצרים את המטען הייעודי (payload) של JWT, צריך להוסיף הצהרה נוספת בהרשאה
קטע שבו המפתח vehicleid
או tripid
מוגדר לערך של
מזהה הרכב או מזהה הנסיעה שבשבילם מתבצעת השיחה.
ה-SDK של מנהל ההתקן תמיד משתמש בהצהרה vehicleid
, גם אם היא פועלת
טיול או רכב. הקצה העורפי של Fleet Engine מבטיח שהרכב
משויכת לנסיעה המבוקשת לפני ביצוע השינוי.
ב-SDK לצרכן נעשה תמיד שימוש בהצהרה tripid
.
ספק הנסיעה המשותפת או ספק המשלוחים צריך להשתמש ב-vehicleid
או ב-tripid
עם הסימן "*" אל
התאמה לכל כלי הרכב והנסיעות. שימו לב שה-JWT יכול להכיל את שני האסימונים,
גם אם אין בכך צורך, מה שעשוי לפשט את ההטמעה של חתימת האסימונים.
תרחישים לדוגמה של JWT
הקוד הבא מציג אסימון לדוגמה עבור שרת ספק:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
בדוגמה הבאה מוצג אסימון של אפליקציה לצרכנים:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
הטבלה הבאה מציגה אסימון לדוגמה עבור אפליקציית Drive:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- בשדה
kid
שבכותרת, מציינים את המפתח הפרטי של חשבון השירות ID. אפשר למצוא את הערך הזה בשדהprivate_key_id
של השירות קובץ JSON של החשבון. - בשדות
iss
ו-sub
, צריך לציין את כתובת האימייל של חשבון השירות. אפשר למצוא את הערך הזה בשדהclient_email
בחשבון השירות קובץ JSON. - בשדה
aud
מציינים https://SERVICE_NAME/. - בשדה
iat
, משתמשים בחותמת הזמן של מועד היצירה של האסימון, מצוין כשניות שחלפו מאז 00:00:00 UTC, 1 בינואר 1970. ממתינים 10 דקות להטיה. אם חותמת הזמן רחוקה מדי בעבר, או שבעתיד, השרת עשוי לדווח על שגיאה. - בשדה
exp
, משתמשים בחותמת הזמן כשפג תוקף האסימון, צוין בשניות מאז 00:00:00 UTC, 1 בינואר 1970. הערך המקסימלי הערך המותר הואiat
+ 3600.
כשחותמים על ה-JWT להעברה למכשיר נייד, צריך לוודא חשבון השירות של תפקיד ה-SDK לנהג או לצרכן. אחרת, הנייד יוכל לשנות את המצב שבו המכשיר לא אמור להיות.
כמו כן, כשחותמים על ה-JWT שישמשו לשיחות בעלות הרשאות, צריך לוודא כדי להשתמש בחשבון השירות עם תפקיד Super User. אחרת, הפרמטר הפעולה תיכשל.
יצירת JWT לבדיקה
יצירת אסימונים מהטרמינל יכולה להועיל במהלך הבדיקה.
כדי לבצע את השלבים האלה, המשתמש שלך צריך להיות לכם חשבון עם התפקיד 'יצירת אסימונים בחשבון שירות':
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
יצירת קובץ חדש בשם unsigned_token.json
עם התוכן שמפורט בהמשך. iat
הוא הזמן הנוכחי במספר השניות אחרי תחילת התקופה, שיכולה להיות
האחזור מתבצע על ידי הרצת date +%s
במסוף שלך. הנכס exp
הוא
את מספר השניות לאחר epoch, שניתן לחשב לפי
מוסיף את 3600 ל-iat
. זמן התפוגה לא יכול להיות יותר משעה אחת
העתידי.
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
לאחר מכן מריצים את הפקודה הבאה ב-gcloud כדי לחתום על האסימון בשם חשבון שירות למשתמש:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
JWT חתום בקידוד Base64 אמור להיות מאוחסן עכשיו בקובץ
signed_token.jwt
האסימון תקף לשעה הבאה.
עכשיו אפשר לבדוק את האסימון על ידי הרצת הפקודה curl
על 'רשימת כלי רכב'.
נקודת קצה ב-REST:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
כלי רכב ומחזור החיים שלהם
כלי הרכב הוא הישות שמייצגת את צמד כלי הרכב הנהגיים. נכון לעכשיו, לא ניתן לעקוב אחר נהג ורכב בנפרד. ספק הנסיעה המשותפת או ספק המשלוחים יוצר רכב באמצעות מזהה ספק (שחייב להיות זהה מזהה הפרויקט ב-Google Cloud שמכיל את חשבון השירות שמשמש להפעלת ממשקי ה-API של Fleet Engine) ומזהה רכב בבעלות ספק שירותי הסעה או מסירה.
רכב שלא עודכן דרך UpdateVehicle
אחרי שבעה ימים
תימחק אוטומטית, והנסיעות שהוקצו לה, אם יש כאלה, יסומנו בתור
המשימה לא הוקצתה. הגישה המומלצת כדי להחזיק רכב בהישג יד
ב-Fleet Engine היא לעדכן את המיקום שלו במרווחי זמן קבועים. עדכונים לרוב
גם שדות אחרים בישות Vehicle
יאריכו את חייה, כל עוד
הערך בשדה החדש שונה מהערך הקיים.
הערה: חלק מהשדות בישות Vehicle
, כמו device_settings
, מיועדים רק לניפוי באגים
שלא נשמרים על ידי Fleet Engine. העדכון שלהן לא
להאריך את חיי הישות Vehicle
.
מדובר בשגיאה אם להתקשר אל CreateVehicle
באמצעות
צמד של מזהה ספק/מזהה רכב שכבר קיים. כשמדובר בכלי רכב
לא מעודכנים לעתים קרובות. אפשר לטפל בשתי דרכים:
CreateVehicle
עם צמד של מזהה ספק/מזהה רכב צפוי ומתבצעת מחיקה
השגיאה אם הרכב כבר קיים. או, התקשרות אל CreateVehicle
לאחר
הפונקציה UpdateVehicle
מחזירה עם שגיאה NOT_FOUND
.
עדכונים לגבי מיקום הרכבים
כדי ליהנות מהביצועים הטובים ביותר עם Fleet Engine, מומלץ לספק סטרימינג של רכב עדכוני מיקום. אפשר לספק את העדכונים האלה באחת מהדרכים הבאות:
- שימוש ב-Driver SDK – Android, iOS -- האפשרות הפשוטה ביותר.
- שימוש בקוד מותאם אישית – שימושי אם מיקומים ממסר דרך הקצה העורפי, או אם אתם משתמשים במכשירים אחרים שהם לא Android או iOS.
סוגים של כלי רכב
הישות 'כלי רכב' מכילה שדה חובה של VehicleType
, שמכיל
enum אחד (Category
) שאפשר לציין בתור AUTO
, TAXI
, TRUCK
,
TWO_WHEELER
, BICYCLE
או PEDESTRIAN
. סוג הרכב יכול לשמש
קריטריונים לסינון SearchVehicles
ו-ListVehicles
.
כל המסלולים של כלי הרכב ישתמשו בRouteTravelMode
המתאים, אם
הקטגוריה שמוגדרת היא AUTO
, TWO_WHEELER
, BICYCLE
או PEDESTRIAN
.
אם הקטגוריה מוגדרת לערך TAXI
או TRUCK
, הניתוב יטופל כמו
מצב AUTO
.
מאפייני הרכב
ישות הרכב מכילה שדה חוזר של VehicleAttribute
. האלה
המאפיינים לא מפורשים על ידי Fleet Engine. SearchVehicles
ה-API כולל שדה שמחייב את הערך של המאפיין Vehicles
התואם חייב להכיל את כל הערכים
את המאפיינים הכלולים המוגדרים לערך שצוין.
שימו לב ששדה המאפיין הוא בנוסף לכמה שדות נתמכים אחרים
בהודעה Vehicle
, למשל vehicle_type
ו-supported_trip_types
.
ציוני דרך שנותרו ברכב
ישות הרכב מכילה שדה חוזר של TripWaypoint
(RPC | REST),
שנקראה waypoints
(RPC | REST).
שדה זה כולל את שאר ציוני הדרך בנסיעות, לפי הסדר
הרכב מגיע אליהם. Fleet Engine מחשב את השדה הזה כמו שהנסיעות
שהוקצו לרכב, ומעדכנים אותו כשהסטטוס של הנסיעות משתנה.
אפשר לזהות את ציוני הדרך האלה לפי השדה TripId
והשדה WaypointType
.
הרחבת הכשירות של רכבים להתאמות
בדרך כלל, השירותים של נסיעה משותפת או ספק משלוחים אחראים על התאמת הנסיעה.
בקשות לכלי רכב. השירות יכול להשתמש במאפייני הרכב כדי לכלול
במספר גדול יותר של חיפושים. לדוגמה, הספק יכול להטמיע
קבוצה של מאפיינים שתואמים לרמות של ההטבות או היכולות שמסופקות על ידי
רכב. לדוגמה, שלוש רמות יכולות להיות קבוצה של מאפיינים עם ערך בוליאני
ערכים: is_bronze_level
, is_silver_level
ו-is_gold_level
. כלי רכב
יכול להיות כשיר לכל שלושת הסוגים. כש-Fleet Engine מקבל בקשה
נסיעה שמחייבת יכולות ברמת 'כסף', החיפוש כולל את כלי הרכב הזה.
שימוש במאפיינים בדרך הזו כולל כלי רכב שמציעים מגוון של
יכולות.
יש שתי דרכים לעדכן את מאפייני הרכב. האחד הוא UpdateVehicle
API. כשמשתמשים ב-API הזה, כל מאפייני הרכב
מוגדר לערך. לא ניתן לעדכן רק מאפיין אחד.
השיטה השנייה היא API UpdateVehicleAttributes
. בשיטה הזאת לוקח רק
של המאפיינים שיעודכנו. המאפיינים הכלולים בבקשה יהיו
מוגדר לערך החדש או שנוסף, מאפיינים שלא צוינו לא ישתנו.
איך: יצירת רכב
צריך ליצור ישות Vehicle
לכל רכב שיהיה מעקב אחריו בכלל.
משתמשים בנקודת הקצה CreateVehicle
עם ה-CreateVehicleRequest
כדי ליצור
רכב.
הערך provider_id
של Vehicle
חייב להיות מזהה הפרויקט
(למשל, my-on-demand-project) של הפרויקט ב-Google Cloud שמכיל את
חשבונות שירות שישמשו לקריאה ל-Fleet Engine. שימו לב שבזמן
מספר חשבונות שירות יכולים לגשת ל-Fleet Engine עבור אותה נסיעה משותפת
או ספק מסירה, Fleet Engine לא תומך כרגע בחשבונות שירות של
מספר פרויקטים ב-Google Cloud שניגשים לאותו Vehicles
.
אפשר ליצור את Vehicle
במצב OFFLINE
או ONLINE
. אם המיקום
נוצר ב-ONLINE
, אפשר להחזיר אותו באופן מיידי בתגובה ל-SearchVehicles
שאילתות.
יכול להיות ש-last_location
ראשוני תיכלל בשיחה של CreateVehicle
.
מותר, אבל אין ליצור Vehicle
במצב ONLINE
בלי
last_location
.
להצגת פרטים על הרכב, אפשר לעיין בקטע סוגי רכב. שדה סוג.
פרטים נוספים זמינים במאמר מאפייני רכב בשדה המאפיינים.
הערך שהוחזר מ-CreateVehicle
הוא הישות Vehicle
שנוצרה.
דוגמה
מעטפת
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
צפייה providers.vehicles.create הפניה.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
יומנים של Google Cloud Platform ליצירת רכב
ה-Fleet Engine API כותב רשומה ביומן באמצעות היומנים של פלטפורמת Google Cloud כאשר
התקבלה קריאה לנקודת הקצה (endpoint) CreateVehicle
. הרשומה ביומן כוללת
מידע על הערכים בבקשת CreateVehicle
. אם השיחה
בהצלחה, היא גם תכלול מידע על Vehicle
הוחזרו.
מעטפת
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
צריך להדפיס רשומה שדומה לזו:
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
התראות של Cloud Pub/Sub ליצירת רכב
Fleet Engine API מפרסם התראה באמצעות Cloud Pub/Sub כאשר נוצר. כדי לקבל את ההתראות האלה, יש לפעול לפי הוראות להתאמה אישית כאן.
איך: עדכון מיקום של רכב
אם אתם לא משתמשים ב-Driver SDK כדי לעדכן את מיקום הרכב, אתם יכולים ליצור שיחה ישירה ל-Fleet Engine עם מיקום הרכב. לכל רכב פעיל, המערכות של Fleet Engine מצפה לעדכון מיקום לפחות פעם בדקה, ולכל היותר פעם ב-5 שניות. לעדכונים האלה נדרש רק משתמש SDK של מנהל התקן של Fleet Engine הרשאות.
דוגמה
מעטפת
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
EOM
צפייה providers.vehicles.update הפניה.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
איך: עדכון שדות אחרים של רכבים
עדכונים במאפיינים אחרים של מצב הרכב מתרחשים לעיתים רחוקות יותר מאשר
עדכוני מיקום. נדרשים עדכונים במאפיינים שאינם last_location
הרשאות משתמש-על ב-Fleet Engine.
השדה UpdateVehicleRequest
כולל update_mask
כדי לציין אילו שדות
התנהגות השדה היא כמו במסמכי התיעוד של Protobuf.
מסיכות שדות.
כפי שצוין במאמר מאפייני רכב, אנחנו מעדכנים את
כדי שהשדה attributes
יישמר, צריך לכתוב את כל המאפיינים. הוא
שלא ניתן פשוט לעדכן את הערך של צמד מפתח/ערך אחד
שיחת UpdateVehicle
. כדי לעדכן ערכים של מאפיינים ספציפיים,
אפשר להשתמש ב-API UpdateVehicleAttributes
.
דוגמה
הדוגמה הזו מפעילה את back_to_back
.
מעטפת
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
צפייה providers.vehicles.update הפניה.
Java
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
יומנים של Google Cloud Platform לעדכונים לרכב
ה-Fleet Engine API כותב רשומה ביומן באמצעות היומנים של פלטפורמת Google Cloud כאשר
התקבלה קריאה לנקודת הקצה (endpoint) UpdateVehicle
. הרשומה ביומן כוללת
מידע על הערכים בבקשת UpdateVehicle
. אם השיחה
בהצלחה, היא גם תכלול מידע על Vehicle
הוחזרו.
מעטפת
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
התראות של Cloud Pub/Sub לעדכונים של רכבים
Fleet Engine API מפרסם התראה באמצעות Cloud Pub/Sub כאשר הרכב מעודכן. כדי לקבל את ההתראות האלה, יש לפעול לפי הוראות להתאמה אישית כאן.
איך: חיפוש כלי רכב
Fleet Engine תומך בחיפוש כלי רכב. SearchVehicles
בעזרת API אפשר למצוא מנהלי התקנים זמינים בקרבת מקום שהכי מתאימים למשימה, כמו
שירות נסיעה או בקשת משלוח. ה-API של SearchVehicles
מחזיר
רשימה מדורגת של נהגים שתואמים למאפייני משימה עם מאפיינים של כלי רכב ב:
בכלל. מידע נוסף זמין במאמר הבא:
חיפוש נהגים בקרבת מקום.
דוגמה
כשמחפשים כלי רכב זמינים, Fleet Engine מחריג כלי רכב נסיעות פעילות כברירת מחדל. השירותים של שיתוף הנסיעה או ספק המשלוחים צריכים לכלול אותם במפורש בבקשות חיפוש. הדוגמה הבאה מראה איך לכלול את כלי הרכב האלה בחיפוש של כלי רכב שתואמים לנסיעה מגרנד קניון אינדונזיה מזרח עם מרכז הכנסים בלאי סידאנג ג'אקארטה.
מעטפת
קודם עליך לעדכן את המיקום של הרכב שיצרנו בשלבים הקודמים, כשיר/ה. בעולם האמיתי, הפעולה הזו תתבצע על ידי Driver SDK שרץ במכשיר Android או iOS ברכב.
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"lastLocation": {
"updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
"location": {
"latitude": "-6.195139",
"longitude": "106.820826"
}
},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
ביצוע החיפוש אמור להניב לפחות את הרכב הזה.
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
צפייה providers.vehicles.search הפניה.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
שאילתה בנושא סינון רכב
תמיכה בסינון לפי מאפייני רכבים בSearchVehicles
ובListVehicles
באמצעות שאילתת סינון. לתחביר של שאילתות סינון:
AIP-160 כדי לראות דוגמאות.
הערה: שאילתות הסינון תומכות רק בסינון לפי מאפייני רכב,
לא ניתן להשתמש בהם בשדות אחרים. שאילתת הסינון פועלת כתנאי AND
עם מגבלות אחרות, כמו minimum_capacity
או vehicle_types
SearchVehiclesRequest
HOW-TO: הצגת רשימה של כלי רכב
SearchVehicles
עבר אופטימיזציה לחיפוש מספר קטן של כלי רכב בדירוג
ההזמנה מאוד מהירה ומשמשת בעיקר למציאת נהגים בסביבה המתאימים ביותר
למשימה. עם זאת, לפעמים רוצים למצוא את כל כלי הרכב שעונים על הדרישות של
גם אם יש צורך בדפדוף בין התוצאות. ListVehicles
הוא
שמיועד לתרחיש לדוגמה הזה.
בעזרת ה-API של ListVehicles
אפשר למצוא את כל כלי הרכב שעומדים בקריטריונים מסוימים
אפשרויות הבקשה. ה-API של ListVehicles
מחזיר רשימה מספורת של כלי רכב ב-
הפרויקט שתואם לדרישות מסוימות.
כדי לסנן לפי מאפיינים של רכבים, אפשר לעיין במאמרים הבאים: שאילתה לסינון רכבים.
דוגמה
בדוגמה הזו מתבצע סינון של vehicle_type
ומאפיינים באמצעות
מחרוזת filter
.
מעטפת
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
}
EOM
צפייה providers.vehicles.list הפניה.
Java
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
.setParent(parent)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
ListVehiclesResponse listVehiclesResponse =
vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
נסיעות ומחזור החיים שלהן
ממשק ה-API של Trip ומחזור החיים דומים ל-Automotive API ולמחזור החיים.
ספק הנסיעה המשותפת אחראי על יצירת הנסיעות באמצעות Fleet Engine
ממשקים. Fleet Engine מספק גם שירות RPC,
TripService
ו-REST, provider.trips
הקצר הזה. התשובות שלך יעזרו לנו להשתפר. הממשקים האלה מאפשרים יצירת ישויות נסיעה, בקשות מידע, חיפוש
פונקציונליות ויכולות עדכון.
ל-Trip
יש שדה סטטוס למעקב אחרי ההתקדמות שלו במחזור החיים.
הערכים עוברים מ-NEW
ל-COMPLETE
וגם CANCELED
ו-UNKNOWN_TRIP_STATUS
הקצר הזה. התשובות שלך יעזרו לנו להשתפר. יש לעיין ב-trip_status
ל-RPC
או TripStatus ל-REST.
NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE
השירות יכול לעדכן את הנסיעה אל CANCELED
מכל אחד מהסטטוסים האלה.
כשהשירות יוצר נסיעה, הסטטוס של המנוע מוגדר כ-NEW
. א'
הערך vehicle_id
הוא אופציונלי. בדומה לרכבים, השירותים מוחקים באופן אוטומטי נסיעות שלא הוקצו
לאחר שבעה ימים ללא עדכון. אם השירות מנסה ליצור נסיעה עם
המזהה שכבר קיים, מוחזר שגיאה. נסיעה נחשבת 'פעילה' אם
הסטטוס שלו הוא לא COMPLETE
או CANCELED
. הבחנה זו
חשוב בשדה active_trips
בישות 'רכב' וב-SearchTripsRequest
.
השירות יכול לשנות את vehicle_id
שהוקצו לנסיעה רק במהלך הנסיעה
פעיל. לדוגמה, עושים את זה כשנהג מבטל נסיעה בזמן
המסלול יוקצה מחדש לרכב אחר.
הסטטוס חשוב כשמטמיעים את התכונה 'חזרה אחורה' תמיכה בנסיעה. התמיכה הזו מאפשרת לספק להקצות נסיעה חדשה לרכב בזמן שהרכב נמצא בנסיעה פעילה. הקוד ליצירת נסיעה אחת לאחור זהה לנסיעה אחת ומשתמשת באותה דרך במזהים של כלי הרכב. ה-Fleet Engine מוסיף את המוצא והיעד של הנסיעה החדשה אל נקודות הציון בכלי הרכב. למידע נוסף על נסיעות צמודות, אפשר לעיין יצירת נסיעות עם יעדים מרובים.
ציוני הדרך שנותרו בנסיעה
ישות הנסיעה מכילה שדה חוזר של TripWaypoint
(RPC | REST),
שנקראה remainingWaypoints
(RPC | REST).
השדה הזה כולל את כל נקודות הדרך שבהן הרכב צריך לנסוע לפי הסדר.
לפני נקודת ההורדה הסופית של הנסיעה. הוא מחשב מ
נקודות הדרך שנותרו ברכב.
בתרחישים לדוגמה של 'חזרה אחורה' ו'נסיעות ב-Google', הרשימה הזו מכילה ציוני דרך מהמקורות הבאים:
נסיעות אחרות שיתבצעו לפני הנסיעה הזו, אבל לא כוללות ציוני דרך
אחרי הנסיעה הזו. ניתן לזהות את ציון הדרך ברשימה לפי TripId
שלו
ו-WaypointType
.
היחס בין סטטוס הנסיעה לבין נקודות הציון שנותרו ברכב
נקודות הדרך הנותרות של הרכב (RPC | REST)
מעודכנים כש-Fleet Engine מקבל בקשה לשינוי סטטוס הנסיעה.
ציון הדרך הקודם יוסר מרשימת ציוני הדרך שנותרה ברכב כאשר
tripStatus
(RPC | REST)
השתנה מסטטוס אחר ל-ENROUTE_TO_XXX. כלומר, כאשר
סטטוס הנסיעה השתנה מ-ENROUTE_TO_PICKUP ל-ARRIVED_AT_PICKUP,
נקודת האיסוף עדיין תופיע ברשימת ציון הדרך שנותרה ברכב, אבל בזמן הנסיעה
הסטטוס השתנה ל-ENROUTE_TO_INTERMEDIATE_DESTINATION או ENROUTE_TO_DROPOFF,
נקודת האיסוף תוסר מנקודות הדרך שנותרו ברכב.
הערך הזה זהה עבור ARRIVED_AT_INTERMEDIATE_DESTINATION וגם ENROUTE_TO_INTERMDEDIATE_DESTINATION. כאשר ARRIVED_AT_INTERMEDIATE_DESTINATION, יעד הביניים הנוכחי לא יוסר מיתרת הרכב של ציון הדרך עד שהרכב ידווח שהוא עובר לנקודת הציון הבאה.
אם סטטוס הנסיעה ישתנה ל-COMPLETED
, לא יהיו ציוני דרך בנסיעה הזו
ברשימת נקודות הציון הנותרת של הרכב.
איך עושים את זה: יצירת נסיעה
כדי לעקוב אחרי כל בקשת נסיעה צריך ליצור ישות Trip
ולהתאים את כלי הרכב לצי הרכב. שימוש בנקודת הקצה CreateTrip
עם CreateTripRequest
כדי ליצור נסיעה.
כדי ליצור נסיעה, צריך לשלוח את המאפיינים הבאים:
parent
- מחרוזת שכוללת את מזהה הספק שנוצר במהלך הפרויקט ב-Cloud נוצר.trip_id
– מחרוזת שנוצרה על ידי ספק נסיעה משותפת.trip
– מאגר עם מטא-נתונים בסיסיים שמתארים את הנסיעה.trip_type
– דוגמאות שמייצגות אם לנסיעה יכולים להיות נוסעים נוספים מנקודת מוצא ויעד שונים באותו רכב (SHARED
) או צד אחד בלבד (EXCLUSIVE
).pickup_point
– מיקום הטרמינל שמייצג את נקודת המוצא של טיול. בחומר העזר בנושא RPC או הפניית REST
כשיוצרים נסיעה, אפשר לספק את הפרטים הבאים: number_of_passengers
וגם dropoff_point
ו-vehicle_id
. למרות שאין חובה למלא את השדות האלה, אם תציינו אותם,
הם נשמרים. המערכת מתעלמת מכל שאר שדות הנסיעה. לדוגמה, כל הנסיעות
להתחיל ב-trip_status
של NEW
גם אם עוברים ב-trip_status
CANCELED
בבקשת היצירה.
דוגמה
הדוגמה הבאה יוצרת טיול לקניון גרנד אינדונזיה מזרח. הנסיעה
מיועד לשני נוסעים ומיועד לשני נוסעים. הערך provider_id
של Trip
חייב להיות
זהה למזהה הפרויקט. בדוגמה, ספק שיתוף הנסיעה יצר את
פרויקט ב-Google Cloud, project-id. הפרויקט הזה צריך לכלול את
חשבונות השירות שמשמשים להפעלה של Fleet Engine. סטטוס הנסיעה הוא NEW
.
מאוחר יותר, אחרי שהשירות יתאים לנסיעה לרכב, השירות יכול להתקשר
UpdateTrip
ומשנים את vehicle_id
כשהנסיעה מוקצית לרכב.
מעטפת
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"tripType": "EXCLUSIVE",
"numberOfPassengers": 2,
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
}
}
EOM
צפייה providers.trips.create הפניה.
Java
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
היומנים של Google Cloud Platform ליצירת נסיעה
ה-Fleet Engine API כותב רשומה ביומן באמצעות היומנים של פלטפורמת Google Cloud כאשר
התקבלה קריאה לנקודת הקצה (endpoint) CreateTrip
. הרשומה ביומן כוללת
מידע על הערכים בבקשת CreateTrip
. אם השיחה
יצליח, הוא יכלול גם מידע על Trip
שהוחזר.
איך: עדכון נסיעה
ישות הנסיעה מכילה שדות שמאפשרים מעקב על ידי השירות, עבור
לדווח על התקדמות הנסיעה על ידי ה-SDK של הנהג,
SDK לצרכנים. כדי לעדכן את המאפיינים, צריך להשתמש ב-UpdateTripRequest
הודעה. הפעולה הזו מעדכנת את שדות הנסיעה בהתאם ל-field_mask
של הבקשה.
פרטים נוספים זמינים ב-UpdateTripRequest.
ספק נסיעה משותפת אחראי לעדכן את המאפיינים הבאים:
- סטטוס הנסיעה.
- מזהה הרכב. בזמן היצירה או אחרי התאמת הרכב טיול.
- שינויים באיסוף, במסירה או בנקודות ציון.
Fleet Engine מעדכן באופן אוטומטי את השדות הבאים כאשר משתמשים ב- תכונת שיתוף התהליך דרך Driver SDK או Consumer SDK:
- מסלולים
- זמן הגעה משוער
- המרחק שנותר
- מיקום הרכב
- ציוני דרך שנותרו
אפשר לעיין במאמר Trip
ב-RPC או
Resource.Trip
ב-REST.
יומנים של Google Cloud Platform לעדכוני נסיעה
ה-Fleet Engine API כותב רשומה ביומן באמצעות היומנים של פלטפורמת Google Cloud כאשר
התקבלה קריאה לנקודת הקצה (endpoint) UpdateTrip
. הרשומה ביומן כוללת
מידע על הערכים בבקשת UpdateTrip
. אם השיחה מצליחה,
הוא יכלול גם מידע על Trip
שהוחזר.
איך: חיפוש נסיעות
Fleet Engine תומך בחיפוש נסיעות. כפי שצוין קודם, נסיעה היא
נמחק באופן אוטומטי אחרי שבעה ימים, כך ש-SearchTrips
לא
לחשוף את ההיסטוריה המלאה של כל הנסיעות.
SearchTrips
הוא API גמיש, אבל הרשימה הבאה מתייחסת לשני תרחישים לדוגמה.
קביעת נסיעות פעילות של הרכב – הספק יכול לקבוע את הנסיעות הפעילות של הרכב כרגע. בתוך
SearchTripsRequest
, היעדvehicle_id
הוגדר לרכב המשוקלל ו-active_trips_only
צריך להגדיר את הערךtrue
.התאמה של הספק למצב של מנוע החיפוש (Fleet Engine) – הספק יכול להשתמש
SearchTrips
כדי להבטיח את מצב הנסיעה שלהם ואת מצב ההתאמה של Fleet Engine. זה חשוב במיוחד לגבי TripStatus. אם המדינה של הנסיעה הוקצתה לרכב לא מוגדר כראוי כ-COMPLETE
אוCANCELED
, הרכב לא נכלל על ידיSearchVehicles
.
כדי להשתמש במאפיין SearchTrips
בצורה הזו, צריך להשאיר את השדה vehicle_id
ריק, להגדיר את active_trips_only
ל-true
, ומגדירים את minimum_staleness
לזמן ארוך יותר מרוב משכי הנסיעה.
לדוגמה, תוכלו להשתמש בערך של שעה אחת. התוצאות כוללות נסיעות שלא
הושלם או בוטל, ולא עודכנו במשך יותר משעה. הספק
לבדוק את הנסיעות האלה כדי לוודא שהסטטוס שלהן ב-Fleet Engine הוא
עודכן כראוי.
פתרון בעיות
במקרה של שגיאת DEADLINE_EXCEEDED
, המצב של Fleet Engine הוא
לא ידועה. הספק צריך להתקשר שוב אל CreateTrip
, והפעולה הזו תחזיר
201 (CREATED) או 409 (CONFLICT). במקרה השני, הבקשה הקודמת הצליחה
עד DEADLINE_EXCEEDED
. מידע נוסף זמין במדריכים לצרכנים API
מידע על טיפול בשגיאות נסיעה: Android
או iOS.
תמיכה בנסיעות ב-Carpool
אפשר להקצות כמה נסיעות של SHARED
לרכב שתומך ב-TripType.SHARED
.
עליך לציין את הסדר של כל נקודות הדרך שלא עברו בכל הנסיעות שהוקצו אל
הרכב בנסיעה המשותפת הזו דרך Trip.vehicle_waypoints
אם מקצים את
vehicle_id
לנסיעה משותפת (בבקשה של CreateTrip
או UpdateTrip
).
יש לעיין ב-vehicle_waypoints
ל-RPC
או vehicleWaypoints
ל-REST.
תמיכה ביעדים מרובים
זיהוי של יעד ביניים
השדה intermediateDestinations
והשדה intermediateDestinationIndex
בטיול (RPC | REST)
משולבים כדי לציין את היעד.
עדכון יעד הביניים
אפשר לעדכן את יעדי הביניים דרך UpdateTrip
. בזמן העדכון
יעדי ביניים, צריך לספק רשימה מלאה של יעדי ביניים
כולל אלה שכבר ביקרו בהם, לא רק האתר החדש
להוסיף או לבצע שינוי.
כשה-intermediateDestinationIndex
מצביע על מדד אחרי המיקום של
יעד ביניים שנוסף/השתנה לאחרונה, רמת הביניים החדשה/המעודכנת
היעד לא יתווסף לwaypoints
של הרכב או ל-remainingWaypoints
של הנסיעה.
הסיבה לכך היא שכל יעדי הביניים לפני intermediateDestinationIndex
יטופלו כאנשים שכבר ביקרו בהם.
שינויים בסטטוס הנסיעה
השדה intermediateDestinationsVersion
ב-(RPC | REST)
נדרש בבקשה לעדכון סטטוס הנסיעה שנשלחה אל Fleet Engine כדי לציין
עבר יעד ביניים. יעד הביניים המטורגט
מצוין באמצעות השדה intermediateDestinationIndex
.
כשהערך של tripStatus
(RPC | REST) הוא ENROUTE_TO_INTERMEDIATE_DESTINATION, מספר בין
[0..N-1] מציין את יעד הביניים הבא שבו הרכב יעבור.
כשהערך של tripStatus
הוא ARRIVED_AT_INTERMEDIATE_DESTINATION, מספר בין
[0..N-1] מציין את יעד הביניים שבו נמצא הרכב.
דוגמה
הקוד הבא לדוגמה ממחיש איך לעדכן סטטוס של נסיעה כך ליעד הביניים הראשון, בהנחה שיצרתם נסיעה עם כמה יעדים, והנסיעה עברה את נקודת האיסוף שלה.
Java
static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";
String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
// Trip settings to update.
Trip trip = Trip.newBuilder()
// Trip status cannot go back to a previous status once it is passed
.setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
// Enrouting to the first intermediate destination.
.setIntermediateDestinationIndex(0)
// intermediate_destinations_version MUST be provided to ensure you
// have the same picture on intermediate destinations list as FleetEngine has.
.setIntermediateDestinationsVersion(
trip.getIntermediateDestinationsVersion())
.build();
// Trip update request
UpdateTripRequest updateTripRequest =
UpdateTripRequest.newBuilder()
.setName(tripName)
.setTrip(trip)
.setUpdateMask(
FieldMask.newBuilder()
.addPaths("trip_status")
.addPaths("intermediate_destination_index")
// intermediate_destinations_version must not be in the
// update mask.
.build())
.build();
// Error handling
try {
Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND: // Trip does not exist.
break;
case FAILED_PRECONDITION: // The given trip status is invalid, or the
// intermediate_destinations_version
// doesn’t match FleetEngine’s.
break;
case PERMISSION_DENIED:
break;
}
return;
}
איך: הרשמה לקבלת התראות מ-Fleet Engine API
ב-Fleet Engine API משתמשים ב- Google Cloud Pub/Sub לפרסם התראות בנושא שנוצר על ידי הצרכן ב-Google Cloud פרויקט. Pub/Sub לא מופעל כברירת מחדל ל-Fleet Engine ב-Google Cloud פרויקט. צריך לשלוח בקשת תמיכה או לפנות למהנדסים של הלקוח כדי להפעיל את Pub/Sub.
כדי ליצור נושא בפרויקט Cloud, צריך לפעול לפי ההוראות האלה. מזהה הנושא חייב להיות fleet_engine_notifications.
צריך ליצור את הנושא באותו פרויקט ב-Cloud שקורא ל-Fleet Engine ממשקי API.
אחרי יצירת הנושא, יהיה עליך להעניק את Fleet Engine API
הרשאה לפרסם בנושא. כדי לעשות זאת, יש ללחוץ על הנושא
נוצר ומוסיפים הרשאה חדשה. יכול להיות שתצטרכו ללחוץ על הצגת חלונית המידע כדי לפתוח את עורך ההרשאות.
חשבון המשתמש צריך להיות geo-fleet-engine@system.gserviceaccount.com
והתפקיד צריך להיות Pub/Sub publisher
.
כדי להגדיר בפרויקט ב-Cloud הרשמה להתראות: לפעול לפי ההוראות האלה.
כל התראה תפורסם בשני נתונים שונים על ידי Fleet Engine API
פורמטים, protobuf
json
פורמט הנתונים של כל התראה מצוין
מאפייני PubsubMessage
שהמפתח הוא data_format
והערך שלו הוא protobuf
או json
.
סכימת התראות:
פרוטובוף
// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
// Required. At least one notification must exist.
// List of notifications containing information related to changes in
// Fleet Engine data.
repeated Notification notifications = 1;
}
// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
// Required. At least one type must exist.
// Type of notification.
oneof type {
// Notification related to changes in vehicle data.
VehicleNotification vehicle_notification = 1;
}
}
// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
// Required.
// Vehicle must contain all fields that were set when it was created.
Vehicle vehicle = 1;
}
// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
// Required.
// Vehicle must only contain name and fields that are present in the
// field_mask field below.
Vehicle vehicle = 1;
// Required.
// Contains vehicle field paths that were specifically requested
// by the Provider.
google.protobuf.FieldMask field_mask = 2;
}
// Notification related to changes in vehicle data.
message VehicleNotification {
// Required. At least one type must be set.
// Type of notification.
oneof type {
// Notification sent when a new vehicle was created.
CreateVehicleNotification create_notification = 1;
// Notification sent when an existing vehicle is updated.
UpdateVehicleNotification update_notification = 2;
}
}
JSON
BatchNotification: {
"description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
"type": "Notification[]"
}
}
}
Notification: {
"description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
"type": "object",
"properties": {
"vehicleNotification": {
"description": "Notification related to changes in vehicle data.",
"type": "VehicleNotification"
}
}
}
VehicleNotification: {
"description": "Notification related to changes in vehicle data.",
"type": "object",
"properties": {
"createNotification": {
"description": "Notification sent when a new vehicle was created.",
"type": "CreateVehicleNotification"
},
"updateNotification": {
"description": "Notification sent when an existing vehicle is updated.",
"type": "UpdateVehicleNotification"
}
}
}
CreateVehicleNotification: {
"description": "Notification sent when a new vehicle was created.",
"type": "object",
"required": ["vehicle"],
"properties": {
"vehicle": {
"description": "Vehicle must contain all fields that were set when it was created.",
"type": "Vehicle"
}
}
}
UpdateVehicleNotification: {
"description": "Notification sent when an existing vehicle is updated.",
"type": "object",
"required": ["vehicle", "fieldMask"],
"properties": {
"vehicle": {
"description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
"type": "Vehicle"
},
"fieldMask": {
"description": "Contains vehicle field paths that were specifically requested by the Provider.",
"type": "FieldMask"
}
}
}