Update selected routes

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

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