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 ו-dynamicRouting (אם הנתיב קבוע או דינמי). כשמעדכנים את נקודות הדרך במסלול (dynamicRoute), צריך לספק את כל האובייקט dynamicRoute (נקודת המוצא, היעד ונקודות הדרך שביניהם). אי אפשר לעדכן שדות משנה באופן חלקי. אי אפשר לשנות שדות מערכת לקריאה בלבד, כמו name,‏ createTime ו-state. הנתונים ההיסטוריים ב-BigQuery שומרים את הנתונים של נקודות הדרך הקודמות והמעודכנות באותו selectedRouteId. אם אתם צריכים נתונים היסטוריים נפרדים, צרו מסלול חדש במקום לבצע עדכון.

עדכון נקודות הדרך של המסלול (dynamicRoute) מפעיל אימות מחדש של המסלול. השדות static_route_geometry ו-road_segment_ids בטבלה routes_status ב-BigQuery מתעדכנים בהתאם.

אפשר לעדכן את נקודות הדרך כשהמסלול נמצא בסטטוס STATE_RUNNING או STATE_INVALID, ואי אפשר לעדכן אותן כשהמסלול נמצא בסטטוס STATE_VALIDATING או STATE_DELETING. מידע נוסף זמין במאמר מצבי אימות ומסלול. מותר לעדכן מטא-נתונים כמו displayName,‏ routeAttributes או dynamicRouting בכל המדינות חוץ מ-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",
  "dynamicRouting": TRUE_OR_FALSE
}

עדכון מסלולים בחבילה

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

שולחים בקשת POST לנקודת הקצה (endpoint) של batchUpdate:

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

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

הפרמטר updateMask הוא אופציונלי ומציין את רשימת השדות שצריך לעדכן (displayName,‏ routeAttributes,‏ dynamicRouting או האובייקט dynamicRoute כולו). הערך updateMask=* מציין החלפה מלאה. אפשר לציין updateMask בתוך כל פריט בנפרד ב-requests, או להעביר אותו לרמה העליונה של גוף בקשת ה-Batch כדי להחיל אותו על כל המסלולים המעודכנים ב-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",
      "dynamicRouting": TRUE_OR_FALSE
    },
    {
      "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",
      "dynamicRouting": TRUE_OR_FALSE
    }
  ]
}