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

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

ایجاد مسیر

برای ایجاد مسیر، درخواست 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 '
    {
      "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 است. برای بازیابی یا حذف منبع SelectedRoute می‌توانید از این selectedRouteId استفاده کنید.

نمونه کد زیر ساختار پاسخ نقطه پایانی 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"
}

ساختن مسیر با ایستگاه‌های بین راهی

برای ایجاد مسیری که از نقاط خاصی بین مبدأ و مقصد عبور می‌کند، آرایه‌ای از 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"
    },
    {
      "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"
    }
  ]
}