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

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

ایجاد یک مسیر

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

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

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

  • یک شیء dynamicRoute با اطلاعات زیر:
    • origin مسیر انتخاب شده.
    • destination مسیر انتخاب شده.
    • هرگونه intermediates ، که به عنوان نقاط بین‌راهی نیز شناخته می‌شوند، در مسیر.
  • یک selectedRouteId منحصر به فرد. این مقدار باید بین ۴ تا ۶۳ کاراکتر باشد و فقط از کاراکترهای الفبایی-عددی استفاده کند . اگر شناسه‌ای ارائه ندهید، سیستم یک شناسه منحصر به فرد برای مسیر انتخاب شده ایجاد می‌کند.

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

curl -X POST -d '
    {"dynamic_route": { \
      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"
}

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

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

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

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

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

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

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

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "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"
    },
    {
      "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
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

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

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

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

curl -X POST -d '
    {"dynamic_route": { \
        "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"

استفاده از ویژگی‌های مسیر سفارشی

برای بهبود مدیریت مسیر و تحلیل داده‌ها در Roads Management Insights، شیء SelectedRoute شامل یک فیلد route_attributes است.

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

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

در زیر چند نمونه از ویژگی‌های مسیر که می‌توانید استفاده کنید، آورده شده است:

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

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

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

سپس می‌توانید از این routeAttributes سفارشی در Roads Management Insights به روش‌های زیر استفاده کنید:

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

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

curl -X POST -d '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"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"