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

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

• ایجاد مسیر : یک مسیر را با استفاده از نقطه پایانی create تعریف کنید.
• مسیرهای ایجاد دسته ای : چندین مسیر را در یک درخواست با استفاده از نقطه پایانی batchCreate تعریف کنید.
• ایجاد مسیر با ایستگاه های بین راهی : مسیری را با حداکثر 25 ایستگاه بین راهی تعریف کنید.
• از ویژگی‌های مسیر سفارشی استفاده کنید : حداکثر 10 جفت کلید-مقدار سفارشی را برای اهداف سازمانی به مسیرهای خود اضافه کنید.

یک مسیر ایجاد کنید

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

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

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

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

هشدار: selectedRouteId از کاراکترهای خاص از جمله زیرخط و دو نقطه پشتیبانی نمی کند. اگر یک نویسه خاص به selectedRouteId خود اضافه کنید، API یک خطای INVALID_ARGUMENT برمی‌گرداند.

نمونه کد زیر ساختار یک درخواست 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 را برمی گرداند. پاسخ شامل RouteId 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 استفاده کنید. این نقطه پایانی به شما امکان می دهد تا 1000 مسیر را در یک تماس تعریف کنید.

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

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

URL از دستور GRPC Transcoding استفاده می کند.

بدنه درخواست باید یک شی 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 آن تعریف می شود، یک مسیر می تواند تا 25 نقطه بین داشته باشد.

نمونه کد زیر نحوه ایجاد 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 شروع شوند.
• طول هر کلید و هر مقدار نباید از 100 کاراکتر تجاوز کند.

سپس می‌توانید از این 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"