תחילת העבודה עם Fleet Engine

ממשק ה-API של Fleet Engine ליצירת נסיעות ולמשלוחים על פי דרישה מאפשר לנהל נסיעות ואת מצב הרכב באפליקציות שלך ל'נסיעה' ו'התקדמות הזמנה'. הוא מטפל בעסקאות בין Driver SDK, ה-SDK לצרכן שירות לקצה העורפי – שיכול לתקשר עם Fleet Engine באמצעות ב-gRPC או קריאות REST.

דרישות מוקדמות

לצורכי פיתוח, צריך להתקין את הענן ב-SDK (gcloud) ומאומתים בפרויקט שלכם.

הערה: מומלץ להשתמש בסביבה האינטראקטיבית של Cloud Shell שבה Cloud SDK יחסי תלות אחרים כמו curl כבר מותקנים. למידע נוסף, ראו שימוש ב-Cloud Shell.

מעטפת

gcloud auth login

אתם אמורים לראות הודעה כמו:

You are now logged in as [[e-mail]].
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:

1. יוצרים פרויקט ב-Google Cloud באמצעות מסוף Google Cloud.
2. באמצעות מרכז השליטה של ממשקי ה-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 מותאמות אישית. יש להגביל את התפקיד הזה לסביבות מהימנות (הקצה העורפי של הלקוח).
FleetEngine Service Super User **(DEPRECATED)** 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:[e-mail] \
       --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:[e-mail] \
       --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:[e-mail] \
       --role=roles/fleetengine.serviceSuperUser

ערכות ה-SDK לנהגים ולצרכנים מבוססות על התפקידים הרגילים האלה.

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

מטעמי נוחות, אם אתם צריכים ליצור אסימוני JWT עבור לקוחות לא מהימנים, ניתן להוסיף משתמשים בתפקיד 'יצירת אסימונים בחשבון שירות', מאפשרים להם ליצור אסימונים באמצעות כלי שורת הפקודה של gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

כאשר [e-mail] הוא האימייל המשמש ביצוע אימות באמצעות gcloud (gcloud auth list --format='value(account)').

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

ספריית אימות של Fleet Engine

ב-Fleet Engine משתמשים באסימוני JWT (JSON Web Tokens) כדי להגביל את הגישה אל ממשקי API של Fleet Engine. הספרייה החדשה של Fleet Engine Auth, זמין ב-GitHub, מפשטת את בניית אסימוני JWT של Fleet Engine וחותמת עליהם באופן מאובטח.

הספרייה מספקת את היתרונות הבאים:

• מפשט את תהליך היצירה של אסימוני Fleet Engine.
• מספקת מנגנוני חתימת אסימונים שאינם שימוש בקובצי פרטי כניסה (כמו התחזות לחשבון שירות).
• מצרף אסימונים חתומים לבקשות יוצאות שנשלחות מ-stub של gRPC או לקוח GAPIC.

חשוב: מומלץ מאוד להשתמש ב-Fleet Engine Auth Library עם כל הטמעות Java.

יצירת אסימון רשת מבוסס 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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "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:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

יצירת קובץ חדש בשם unsigned_token.json עם התוכן שמפורט בהמשך. iat הוא הזמן הנוכחי במספר השניות אחרי תחילת התקופה, שיכולה להיות האחזור מתבצע על ידי הרצת date +%s במסוף שלך. הנכס exp הוא את מספר השניות לאחר epoch, שניתן לחשב לפי מוסיף את 3600 ל-iat. זמן התפוגה לא יכול להיות יותר משעה אחת העתידי.

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

לאחר מכן מריצים את הפקודה הבאה ב-gcloud כדי לחתום על האסימון בשם חשבון שירות למשתמש:

gcloud beta iam service-accounts sign-jwt --iam-account=[e-mail] 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, מומלץ לספק סטרימינג של רכב עדכוני מיקום. אפשר לספק את העדכונים האלה באחת מהדרכים הבאות:

1. שימוש ב-Driver SDK – Android, iOS -- האפשרות הפשוטה ביותר.
2. שימוש בקוד מותאם אישית – שימושי אם מיקומים ממסר דרך הקצה העורפי, או אם אתם משתמשים במכשירים אחרים שהם לא 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 כדי ליצור רכב.

הערה: ב-CreateVehicle נדרש חשבון עם תפקיד Super User ב-Fleet Engine.

הערך 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. מסיכות שדות.

הערה: השדה update_mask צריך להיות מוגדר תמיד. לא מגדיר את כברירת מחדל, כל השדות כתובים בשדה update_mask. התוצאה עלולה להיות התנהגות לא מכוונת.

כפי שצוין במאמר מאפייני רכב, אנחנו מעדכנים את כדי שהשדה 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

הערה: מומלץ מאוד להשתמש בשדה השאילתה filter מעל required_attributes, required_one_of_attributes וגם required_one_of_attributes_sets שדות, כי filter נועד להחליף בשדות האלה. אם צוין ערך שאינו ריק בשדה filter, השדות הבאים חייבים להיות ריקים: required_attributes, required_one_of_attributes ו-required_one_of_attributes_sets.

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

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

ציוני הדרך שנותרו בנסיעה

ישות הנסיעה מכילה שדה חוזר של 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 בבקשת היצירה.

הערה: כדי להשתמש ב-CreateTrip נדרשים פרטי הכניסה לחשבון בעל ההרשאות שצוין. בהגדרת הפרויקט ב-Cloud.

דוגמה

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

הערה: כדי להשתמש ב-UpdateTripRequest לעדכון trip_status או vehicle_id של נסיעה, נדרש לחשבון בעל ההרשאות של הספק.

ספק נסיעה משותפת אחראי לעדכן את המאפיינים הבאים:

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

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.

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

תמיכה ביעדים מרובים

זיהוי של יעד ביניים

השדה 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.

הערה: השימוש ב-Pub/Sub לא מבטיח את סדר ההודעות.

כדי ליצור נושא בפרויקט Cloud, צריך לפעול לפי ההוראות האלה. מזהה הנושא חייב להיות fleet_engine_notifications.

צריך ליצור את הנושא באותו פרויקט ב-Cloud שמבצע קריאה ל-Fleet Engine ממשקי API.

אחרי יצירת הנושא, יהיה עליך להעניק את Fleet Engine API הרשאה לפרסם בנושא. כדי לעשות זאת, יש ללחוץ על הנושא נוצר ומוסיפים הרשאה חדשה. יכול להיות שתצטרכו ללחוץ על הצגת חלונית המידע כדי לפתוח את עורך ההרשאות. חשבון המשתמש צריך להיות [e-mail] והתפקיד צריך להיות 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

• רכב
• FieldMask

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