ایجاد مسیرهای انتخاب‌شده

این صفحه نحوه ایجاد کردن مسیرها و افزودن مشخصه‌های سفارشی بااستفاده از Roads Selection API را در بخش‌های زیر شرح می‌دهد:

برای پیکربندی و صادر کردن تعاریف مسیر به‌صورت بصری، ابزارها و منابع را ببینید. برای بررسی راهبردهای مربوط به هندسه پیچیده جاده‌ها، راهنمای انتخاب مسیر «بینش‌های تحلیلی مدیریت راه‌ها» را ببینید.

ایجاد مسیر

برای ایجاد مسیر، درخواست POST را به نقطه پایانی create ارسال کنید.

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

متن درخواست باید شیء JSON باشد که منبع SelectedRoute را تعریف می‌کند. این شیء اطلاعات زیر را مشخص می‌کند:

  • شیء dynamicRoute با اطلاعات زیر:
    • origin مسیر انتخاب‌شده.
    • destination مسیر انتخاب‌شده.
    • هر intermediates، که به آن نقطه‌مسیر هم گفته می‌شود، در مسیر.
  • selectedRouteId منحصربه‌فرد. این مقدار باید ۴ تا ۶۳ نویسه باشد، و نویسه‌های معتبر عبارتند از a-z،‏ A-Z،‏ 0-9،‏ -، یا _. اگر شناسه‌ای ارائه نشده باشد، سیستم شناسه یکتایی برای مسیر انتخاب‌شده تولید می‌کند.

ایجاد مسیر ثابت (پیش‌فرض)

مسیرها به‌طور پیش‌فرض به‌عنوان مسیرهای ثابت ایجاد می‌شوند و با هندسه مسیر ایستا (صادرشده به جدول BigQuery routes_status) که در زمان ایجاد بدون ترافیک زنده محاسبه شده است مطابقت دارند. این کار باعث می‌شود پایش داده‌های ترافیک بدون تأثیرپذیری از تغییرات شرایط ترافیک به‌طور یکنواخت انجام شود.

می‌توانید فیلد بولی dynamicRouting را در متن درخواست تنظیم کنید تا مشخص کنید مسیر ثابت (false، پیش‌فرض) است یا پویا (true).

نمونه کد زیر ساختار درخواست POST به create مسیر ثابت را نشان می‌دهد.

curl -X POST -d '
    {
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE,
          "longitude": ORIGIN_LONGITUDE
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE,
          "longitude": DESTINATION_LONGITUDE
        }
      }
    }' \
  -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?selectedRouteId=SELECTED_ROUTE_ID"

درصورت موفقیت، API منبع SelectedRoute را برمی‌گرداند. پاسخ شامل selectedRouteId در فیلد name است. می‌توانید از این selectedRouteId برای بازیابی یا حذف منبع SelectedRoute استفاده کنید.

نمونه کد زیر ساختار پاسخ نقطه پایانی موفق create را نشان می‌دهد.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING",
  "dynamicRouting": false
}

ایجاد مسیر پویا

درصورت تمایل، می‌توانید با تنظیم فیلد dynamicRouting روی true، مسیر پویایی ایجاد کنید. هندسه مسیر ممکن است به‌دلیل شرایط ترافیکی متغیر تغییر کند زیرا پلاتفرم مسیریابی Google هربار بهترین مسیر را پیدا می‌کند.

نمونه کد زیر ساختار درخواست POST را برای create مسیر پویا نشان می‌دهد:

curl -X POST -d '
    {
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE,
          "longitude": ORIGIN_LONGITUDE
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE,
          "longitude": DESTINATION_LONGITUDE
        }
      },
      "dynamicRouting": true
    }' \
  -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?selectedRouteId=SELECTED_ROUTE_ID"

نمونه کد زیر ساختار پاسخ نقطه پایانی create موفق را نشان می‌دهد.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING",
  "dynamicRouting": true
}

ایجاد مسیر با نقاط‌مسیر میانی

برای ایجاد مسیری که از نقاط خاصی بین مبدأ و مقصد عبور می‌کند، یک آرایه intermediates را در شیء dynamicRoute در بدنه درخواست خود قرار دهید. هر عنصر در آرایه intermediates یک نقطه‌مسیر است که با latitude و longitude تعریف می‌شود. مسیر می‌تواند حداکثر ۲۵ نقطه‌مسیر داشته باشد.

برای روال‌های مطلوب درباره قرار دادن نقاط‌مسیر میانی در بزرگراه‌های جداشده، روگذرهای چندسطحی، و تونل‌ها، راهنمای انتخاب مسیر «بینش‌های تحلیلی مدیریت راه‌ها» را ببینید.

نمونه کد زیر نحوه ایجاد SelectedRoute با نقطه‌مسیرهای میانی را نشان می‌دهد:

curl -X POST -d '
    {
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE,
          "longitude": ORIGIN_LONGITUDE
        },
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {
          "latitude": DESTINATION_LATITUDE,
          "longitude": DESTINATION_LONGITUDE
        }
      }
    }' \
  -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?selectedRouteId=SELECTED_ROUTE_ID"

استفاده از مشخصه‌های مسیر سفارشی

برای بهبود مدیریت مسیر و تجزیه‌وتحلیل داده‌ها در «بینش‌های تحلیلی مدیریت راه‌ها»، شیء SelectedRoute شامل فیلد routeAttributes است.

از فیلد routeAttributes برای تعریف ویژگی‌های سفارشی خود برای مسیرهای فردی استفاده کنید، که در آن هر مشخصه یک جفت کلید-مقدار است. می‌توانید حداکثر ۲۵ جفت کلید-مقدار سفارشی برای هر مسیر ارائه دهید.

این مشخصه‌ها برای شناسایی مسیرهای خاص یا گروه‌بندی مسیرها براساس معیارهای مرتبط با نیازهای شما مفید هستند.

در زیر چند نمونه از مشخصه‌های مسیر که می‌توانید استفاده کنید آورده شده است:

  • "road_classification": "highway"
  • "maintenance_zone": "north_district"
  • "event_id": "marathon_2024"
  • "pavement_type": "asphalt"

هنگام تعریف فیلد routeAttributes، دستورالعمل‌های زیر را دنبال کنید:

  • کلیدها نباید با پیشوند goog شروع شوند.
  • طول هر کلید و هر مقدار نباید از ۱۰۰ نویسه بیشتر باشد.

سپس می‌توانید از این routeAttributes سفارشی در «بینش‌های تحلیلی مدیریت راه‌ها» به روش‌های زیر استفاده کنید:

  • فیلتر کردن اعلان‌های Pub/Sub: می‌توانید فیلترهایی را روی اشتراک‌های Pub/Sub خود تنظیم کنید تا به‌روزرسانی‌ها را فقط برای مسیرهایی دریافت کنید که با کلیدهای مشخصه خاص و مقادیر مربوطه آن‌ها مطابقت دارند یا ندارند.
  • پالایش تجزیه‌وتحلیل BigQuery: در جدول‌های BigQuery، می‌توانید از این مشخصه‌ها برای فیلتر کردن مسیرهای خاص براساس مقدار مشخصه استفاده کنید. همچنین می‌توانید مسیرها را براساس کلید مشخصه خاصی گروه‌بندی کنید تا تحلیل داده‌ها هدفمندتر شود.

نمونه کد بعدی نحوه ایجاد SelectedRoute با routeAttributes سفارشی را نشان می‌دهد.

curl -X POST -d '
    {
    "dynamicRoute": {
      "origin": {
        "latitude": ORIGIN_LATITUDE,
        "longitude": ORIGIN_LONGITUDE
      },
      "destination": {
        "latitude": DESTINATION_LATITUDE,
        "longitude": DESTINATION_LONGITUDE
      }
    },
    "routeAttributes": {
      "ATTRIBUTE_KEY": "ATTRIBUTE_VALUE"
    }
  }' \
  -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?selectedRouteId=SELECTED_ROUTE_ID"

ایجاد دسته‌ای مسیرها

برای ایجاد چند مسیر در یک درخواست، از نقطه پایانی batchCreate استفاده کنید. این نقطه پایانی به شما امکان می‌دهد تا ۱۰۰۰ مسیر را در یک تماس تعریف کنید.

درخواست POST را به نقطه پایانی batchCreate ارسال کنید:

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

نشانی وب از نحو تراتبدیل gRPC استفاده می‌کند.

متن درخواست باید شیء JSON حاوی آرایه requests باشد. هر شیء در این آرایه یک CreateSelectedRouteRequest است که یک منبع SelectedRoute را تعریف می‌کند.

نمونه کد زیر ساختار درخواست POST به نقطه پایانی batchCreate را نشان می‌دهد:

curl -X POST -d '
    {
      "requests": [
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_1,
                "longitude": ORIGIN_LONGITUDE_1
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_1,
                "longitude": DESTINATION_LONGITUDE_1
              }
            }
          },
          "selectedRouteId": "route-one"
        },
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_2,
                "longitude": ORIGIN_LONGITUDE_2
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_2,
                "longitude": DESTINATION_LONGITUDE_2
              }
            }
          },
          "selectedRouteId": "route-two"
        }
      ]
    }' \
  -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:batchCreate"

درصورت موفقیت، API پاسخی حاوی آرایه‌ای از منابع SelectedRoute ایجادشده برمی‌گرداند.

نمونه کد زیر ساختار پاسخ نقطه پایانی batchCreate را نشان می‌دهد:

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING",
      "dynamicRouting": false
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING",
      "dynamicRouting": false
    }
  ]
}