טיפול בנתוני נסיעות

כשמאחזרים את נתוני הנסיעה, ה-backend מקבל מטען ייעודי (payload) של JSON עם פרטים על התקדמות הנסיעה של הנהג. אפשר לנתח את המטען הייעודי הזה כדי לעקוב אחרי הנסיעה, לעדכן את מערכות השיגור ולפרש את הסטטוסים הנוכחיים של הנסיעה כדי לקבוע מה השלב הבא עבור הנהג במהלך הנסיעה או בסיומה.

קריאת נתוני הפרוטוקולים

מפות Google או Waze שולחות את נתוני הנסיעה לשרתים של Navigation Connect כשהנהג מתחיל בניווט, מעת לעת לאורך המסלול (כל 60 שניות כברירת מחדל) וכשהנהג מגיע ליעד. כל הודעת JSON מכילה נתוני נסיעה רלוונטיים, כולל קואורדינטות של הנהג שמוצמדות לכביש, המרחק שנסע וזמן ההגעה המשוער (ETA). העדכונים האלה משקפים את המסלול הפעיל של הנהג בזמן אמת, ולכן יכול להיות שהם יהיו שונים מהמסלולים שחושבו מראש על ידי ה-Backend שלכם (ראו שאלות נפוצות).

בדוגמת הקוד הבאה מוצג מטען ייעודי (payload) של נתוני נסיעה, כשנהג מתחיל לנווט לנסיעה מ-King's Cross ל-Central St. Giles.

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

הערה: אם אתם מקבלים את הנתונים באמצעות Google Cloud Pub/Sub, השירות עוטף את העדכונים לגבי הנסיעות במעטפת הודעה רגילה. שדה הנתונים מכיל את מטען ה-JSON הייעודי של Navigation Connect.

מעקב אחרי סטטוסים של נסיעות פעילות

כדי לוודא שההתחלה הייתה מוצלחת ולעקוב אחרי ההתקדמות, צריך לבדוק את השדה state בכל מטען ייעודי (payload).

סטטוס	תיאור
NEW	הנסיעה נוצרה, אבל הנהג עדיין לא התחיל לנווט.
ENROUTE	הנהג מנווט באופן פעיל אל היעד. אפשר להשתמש בסטטוס הזה כדי לוודא שהנסיעה אומתה והתחילה בהצלחה.

טיפול בעצירות ביניים שנוספו

הנהגים יכולים להוסיף עצירות למסלול במהלך הניווט. אם הם כן, Navigation Connect מגדיר את השדה execution.stopAddedInRoute לערך true במטען הייעודי (payload) של נתוני ה-JSON. ‫Navigation Connect API ממשיך לעקוב אחרי הנהג לכיוון היעד המקורי. המדדים כמו זמן ההגעה המשוער, המרחק והמשך הנסיעה גדלים כדי לכלול את העצירות הנוספות.

ההתנהגות של הוספת עצירות תלויה באפליקציית הניווט, והיא תואמת לפונקציונליות הרגילה שלה:

• מפות Google: נהגים יכולים להוסיף כמה עצירות למסלול.
• ‫Waze: הנהגים יכולים להוסיף רק עצירה אחת. אם נהג ינסה להוסיף עוד עצירה, Waze יציע לו להתחיל סשן ניווט חדש במקום להוסיף את העצירה למסלול הנוכחי.

לא צריך לשנות את הקלט של ה-Backend כדי לתמוך בתכונה הזו.

פתרון בעיות שקשורות לאימות ולהתחלה

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

אם הסטטוס לא משתנה מ-NEW ל-ENROUTE, יכול להיות שהמכשיר של הנהג מונע את האימות. במקרים האלה, לא נשלחות הודעות שגיאה מ-Navigation Connect. כדאי לבדוק את הדברים הבאים:

• במכשיר של הנהג מותקנת גרסה 5.15.5 ואילך של Waze, או גרסה 26.14 ואילך של מפות Google.
• הנהג לא משתמש ב-Android Auto או ב-Apple CarPlay.
• לנהג יש חיבור אינטרנט פעיל.

טיפול בנתוני מסלולים שנותרו (Waze בלבד)

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

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

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

הפונקציה Navigation Connect מחזירה את פרטי המסלול שנותרו בשדה execution.remainingRoute, בין אם שולחים בקשת GetTrip או מקבלים עדכונים מבוססי-אירועים באמצעות Google Cloud Pub/Sub. עם זאת, הפורמטים והמבנים של מטען הייעודי (payload) של הנתונים האלה תלויים בשיטת השליפה שבה משתמשים.

GetTrip אמצעי תשלום

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

בכל הפורמטים של קווים פוליגוניים, Navigation Connect מחזיר את נתוני התנועה כרשימה נפרדת של אובייקטים מסוג SpeedReadingInterval בשדה execution.remainingRoute.trafficInformation. האובייקטים האלה ממפים את קטגוריות התנועה לאינדקסים של הקו הפוליגוני באמצעות הערכים הבאים:

• ‫startPolylinePointIndex: האינדקס ההתחלתי של מרווח התנועה בקו המרובה נקודות.
• ‫endPolylinePointIndex: האינדקס הסופי של מרווח התנועה.
• ‫speed: קטגוריית התנועה של הפלח הזה: NORMAL,‏ SLOW או TRAFFIC_JAM.

עדכונים ב-Google Cloud Pub/Sub

כשמאחזרים נתוני נסיעה באמצעות Pub/Sub, העדכונים תמיד מחזירים את נתוני המסלול שנותרו ב-GeoJSON מאוחד FeatureCollection בשדה execution.remainingRoute.

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

דוגמה למטען ייעודי (payload) של Pub/Sub

בדוגמת הקוד הבאה מוצג מבנה ה-GeoJSON שמוחזר בשדה execution.remainingRoute באובייקט updatedTrip של הודעת Pub/Sub:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}
    

אופטימיזציה של גודל המטען הייעודי (payload)

מערכי הקואורדינטות גדולים, ולכן הכללת נתוני המסלול שנותרו בהודעות Pub/Sub יכולה להגדיל באופן משמעותי את גודל המטען הייעודי (עד 13-14KB לכל הודעה). אם אתם מקבלים עדכונים בתדירות גבוהה, נפח העדכונים יכול להגדיל את עומס העיבוד בעורף המערכת ואת עלויות השימוש.

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

טיפול בסטייה מהמסלול (Waze בלבד)

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

• על פי דרישה: מבצעים קריאה ל-method‏ GetTrip. השרת שומר את מצב החריגה האחרון הידוע.
• בזמן אמת: אפשר להירשם ל-Google Cloud Pub/Sub. השירות מפרסם עדכוני חריגה באמצעות האירוע הקיים updated_trip תוך 5 שניות מרגע הזיהוי.

קריאת מטען החריגה

אובייקט last_route_deviation מספק את המטא-נתונים הבאים כדי לעזור לכם לנתח את האירוע.

שדה	סוג	תיאור
location	LatLng	הקואורדינטות של קווי הרוחב והאורך שבהן מכשיר הלקוח רשם את הסטייה.
source	TriggerSource	הסיבה לסטייה. השתמשו בזה כדי לקבוע אם הנהג ביצע פעולה לא צפויה או פעל לפי ההנחיות של המערכת: ‫DRIVER_INITIATED_REROUTE: הנהג ביצע בחירה פעילה (לדוגמה, פנייה לא נכונה או בחירה ידנית של נתיב חדש). ‫SYSTEM_INITIATED_REROUTE: אפליקציית הניווט חישבה מסלול חדש (לדוגמה, בגלל שינויים בתנאי התנועה או חסימות בכבישים).
client_timestamp	Timestamp	השעה שבה מכשיר הלקוח זיהה את הסטייה.
server_timestamp	Timestamp	הזמן שבו השרת עיבד את עדכון החריגה.

טיפול במצבי סיום הנסיעה

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

סטטוס	תיאור	הפעולה המומלצת
ARRIVED	הנהג הגיע ליעד.	מומלץ לעיין בremainingDistanceMeters. אם הנהג חנה בקרבת מקום אבל לא במיקום המדויק שצוין, כדאי לספק באפליקציה הוראות הליכה.
SUSPENDED	הנהג יצא ידנית מהניווט במסלול מפורט לפני שהגיע ליעד. מכיוון שמפות Google או Waze לא מחזירות אוטומטית את הנהגים לאפליקציה שלכם כשהם יוצאים מהפעילות לפני הזמן, הנהג צריך להקיש ידנית על לחצן החזרה. הערה: אם הנהג משתמש בלחצן החזרה כדי לחזור לאפליקציה שלכם בלי לצאת מסשן הניווט הפעיל, סטטוס הנסיעה נשאר ENROUTE. מידע נוסף זמין במאמר בנושא מעבר בין אפליקציות במהלך הנסיעה.	כדי לעזור לנהגים להשלים את הנסיעה, משווים בין execution.location לבין היעד. אם נשאר מרחק לנסיעה, צריך לספק לחצן או קישור להמשך הנסיעה או למעבר למצב הליכה.
FAILED	החיבור נקטע בגלל שגיאה טכנית. זה קורה אם האפליקציה לא מצליחה לחשב מסלול או אם מופיעה אזהרת בטיחות. יכול להיות שהנהג עדיין ינווט, אבל לא תקבלו עדכונים.	אפשר לחזור למעקב ידני של הסטטוס באפליקציה.
CLIENT_ERROR	הסטטוס הזה מופיע בגלל אחת מהסיבות הבאות: הנהג מבטל את ההסכמה. הנהג משתמש בפלטפורמה שלא נתמכת, כמו Android Auto או Apple CarPlay. האפליקציה משתמשת מחדש בטוקן נסיעה בכמה נסיעות נפרדות. לדוגמה, ‫Navigation Connect דוחה בקשות לשינוי היעד של נסיעה או לעדכון נסיעה שהסתיימה. הנהג נמצא בארצות הברית בכל שלב במהלך הנסיעה, אבל שיתוף הנתונים בארצות הברית לא מופעל באפליקציה שלכם כשאימתתם את האפליקציה במהלך ההגדרה.	אפשר לחזור למעקב ידני של הסטטוס באפליקציה.