Update selected routes

בדף הזה מוסבר איך לעדכן מסלולים שכבר יצרתם באמצעות Roads Selection API:

עדכון מסלול

כדי לעדכן מסלול, שולחים בקשת PATCH לנקודת הקצה patch:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID?updateMask=UPDATE_MASK

גוף הבקשה חייב להיות אובייקט JSON שמכיל את השדות של SelectedRoute שרוצים לעדכן. השדות שאפשר לעדכן כוללים את displayName,‏ routeAttributes ו-dynamicRoute. כשמעדכנים את הגיאומטריה של המסלול (dynamicRoute), צריך לספק את כל אובייקט dynamicRoute (נקודת המוצא, היעד ונקודות הביניים). אין תמיכה בעדכונים חלקיים של שדות משנה. אי אפשר לשנות שדות מערכת לקריאה בלבד, כמו name, createTime ו-state. הנתונים ההיסטוריים ב-BigQuery ישמרו את הנתונים של הגיאומטריה הישנה והמעודכנת באותו selectedRouteId. אם אתם צריכים נתונים היסטוריים נפרדים, עדיף ליצור מסלול חדש במקום לבצע עדכון.

כדי לעדכן את הגיאומטריה של מסלול (dynamicRoute), צריך לאמת אותו מחדש. מותרים עדכוני גיאומטריה כשהמסלול נמצא במצב STATE_RUNNING או STATE_INVALID, והם נדחים אם המסלול נמצא במצב STATE_VALIDATING או STATE_DELETING. מידע נוסף זמין במאמר אימות ומצבי מסלול. עדכון מטא-נתונים כמו displayName או routeAttributes מותר בכל המצבים חוץ מSTATE_DELETING.

בדוגמת הקוד הבאה אפשר לראות את המבנה של בקשת PATCH לנקודת הקצה patch:

curl -X PATCH -d '{
    "dynamicRoute": {
      "origin": {
        "latitude": 38.5817,
        "longitude": -121.4944
      },
      "destination": {
        "latitude": 38.5449,
        "longitude": -121.7405
      }
    }
  }' \
-H 'X-Goog-User-Project: PROJECT_NUMBER' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
"https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes/"\
"SELECTED_ROUTE_ID?updateMask=dynamicRoute"

אם הפעולה מצליחה, ה-API מחזיר את משאב SelectedRoute המעודכן:

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": 38.5817,
      "longitude": -121.4944
    },
    "destination": {
      "latitude": 38.5449,
      "longitude": -121.7405
    }
  },
  "createTime": "2026-08-14T20:58:41.345418Z",
  "state": "STATE_VALIDATING"
}

חבילת עדכונים של מסלולים

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

שליחת בקשת POST לנקודת הקצה batchUpdate:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchUpdate

גוף הבקשה חייב להיות אובייקט JSON שמכיל מערך requests. כל אובייקט במערך הזה הוא UpdateSelectedRouteRequest שמציין את המסלול name, את updateMask האופציונלי ברמת הפריט ואת השדות selectedRoute לעדכון.

‫updateMask הוא פרמטר אופציונלי שמציין את רשימת השדות לעדכון (displayName,‏ routeAttributes או האובייקט dynamicRoute כולו). ההגדרה updateMask=* מציינת החלפה מלאה. אפשר לציין את updateMask בתוך כל פריט בודד ב-requests, או להעביר אותו לרמה העליונה של גוף בקשת Batch כדי להחיל אותו על כל המסלולים המעודכנים באצווה. אם לא מציינים את updateMask, המערכת מניחה שצריך לעדכן את כל השדות שניתנים לעדכון ומאוכלסים בבקשה. אם מגדירים את updateMask גם ברמת הקבוצה וגם ברמת הפריט, הערכים חייבים להיות זהים. ציון מסכות מתנגשות יוביל לשגיאה INVALID_ARGUMENT.

בדוגמת הקוד הבאה אפשר לראות את המבנה של בקשת POST לנקודת הקצה batchUpdate:

curl -X POST -d '{
    "requests": [
      {
        "selectedRoute": {
          "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
          "displayName": "DISPLAY_NAME_1",
          "dynamicRoute": {
            "origin": {"latitude": 37.5, "longitude": -122.1},
            "destination": {"latitude": 37.8, "longitude": -122.5}
          }
        },
        "updateMask": "displayName,dynamicRoute"
      },
      {
        "selectedRoute": {
          "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
          "displayName": "DISPLAY_NAME_2",
          "dynamicRoute": {
            "origin": {"latitude": 37.5, "longitude": -122.1},
            "destination": {"latitude": 37.8, "longitude": -122.5}
          }
        },
        "updateMask": "displayName,dynamicRoute"
      }
    ]}' \
-H 'X-Goog-User-Project: PROJECT_NUMBER' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
"https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes:batchUpdate"

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

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "displayName": "DISPLAY_NAME_1",
      "dynamicRoute": {
        "origin": {
          "latitude": 37.5,
          "longitude": -122.1
        },
        "destination": {
          "latitude": 37.8,
          "longitude": -122.5
        }
      },
      "createTime": "2026-08-14T20:58:41.345418Z",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "displayName": "DISPLAY_NAME_2",
      "dynamicRoute": {
        "origin": {
          "latitude": 37.5,
          "longitude": -122.1
        },
        "destination": {
          "latitude": 37.8,
          "longitude": -122.5
        }
      },
      "createTime": "2026-08-14T20:58:41.345418Z",
      "state": "STATE_VALIDATING"
    }
  ]
}