این صفحه نحوه ایجاد مسیرها و افزودن مشخصههای سفارشی بااستفاده از «میانای برنامهسازی کاربردی انتخاب جادهها» را در بخشهای زیر شرح میدهد:
- ایجاد مسیر: بااستفاده از
createنقطه پایانی، یک مسیر واحد تعریف کنید. - ایجاد دستهای مسیرها: بااستفاده از نقطه پایانی
batchCreate، چندین مسیر را در یک درخواست تعریف کنید. - ایجاد مسیر با ایستگاههای بین راهی: مسیری با حداکثر ۲۵ ایستگاه بین راهی تعریف کنید.
- استفاده از مشخصههای مسیر سفارشی: حداکثر ۱۰ جفت کلید-مقدار سفارشی برای اهداف سازمانی به مسیرهایتان اضافه کنید.
ایجاد مسیر
برای ایجاد مسیر، درخواست 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"
}
]
}