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

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

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

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

בדוגמת הקוד הבאה מוצג מטען ייעודי (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, השירות עוטף את עדכוני הנסיעות במעטפת הודעה רגילה. שדה הנתונים מכיל את המטען הייעודי (payload) של JSON של Navigation Connect.

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

כדי לוודא שההתחלה הייתה מוצלחת ולעקוב אחרי ההתקדמות, צריך לבדוק את השדה 'סטטוס' בכל מטען ייעודי.

סטטוס	תיאור
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 בלבד)

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

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

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

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

GetTrip method

כשמבצעים קריאה לשיטה 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"
      }
    }
  ]
}
    

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

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

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

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

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

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