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 استفاده کنید. این نقطه پایانی به شما امکان می‌دهد تا ۱۰۰۰ مسیر را در یک تماس به‌روز کنید. به‌روزرسانی‌های دسته‌ای اتمی هستند: اگر هر مسیری در درخواست اعتبارسنجی نشود یا نتوان آن را به‌روزرسانی کرد، هیچ مسیری در دسته اصلاح نمی‌شود.

درخواست POST را به نقطه پایانی 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 مشخص کرد، یا به سطح بالای بدنه درخواست دسته‌ای منتقل کرد تا برای همه مسیرهای به‌روزشده در دسته اعمال شود. اگر 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
    }
  ]
}