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

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

• ایجاد مسیر: یک مسیر واحد را بااستفاده از نقطه پایانی 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 منحصربه‌فرد. این مقدار باید ۴ تا ۶۳ نویسه باشد، و نویسه‌های معتبر عبارتند از a-z، A-Z، 0-9، -، یا _. اگر شناسه‌ای ارائه نشود، سیستم شناسه یکتایی برای مسیر انتخاب‌شده تولید می‌کند.

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

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

درصورت موفقیت، میانای برنامه‌سازی کاربردی منبع 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"
}

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

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