‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

برنامه‌ریزی مسیر

گاهی اوقات ممکن است بخواهید مسیری را که برنامه‌تان به کاربران ارائه می‌دهد برنامه‌ریزی کنید. استفاده از ژتون مسیر از Routes API یا Route Optimization API می‌تواند به شما کمک کند دو چیز را برای مسیر برنامه‌ریزی‌شده‌تان مشخص کنید:

چندخطی برای مسیر
اهداف مسیر شما

برای مثال، در اینجا چند نمونه از اهداف مسیریابی که ممکن است داشته باشید آورده شده است:

به‌حداقل رساندن زمان تحویل: کسب‌وکاری که غذا تحویل می‌دهد ممکن است بخواهد زمان لازم برای تحویل غذا را به‌حداقل برساند.
به‌حداقل رساندن مدت سفر یا مصرف سوخت: یک کسب‌وکار تدارکات ممکن است بخواهد کارایی رانندگان خود را بهبود بخشد و هزینه‌های سوخت خود را کاهش دهد.
کمینه کردن زمان رسیدن به مقصد: عملیات اعزام خدمات ممکن است بخواهد زمان لازم برای رساندن اپراتورها به درخواست کار را کمینه کند.
کاهش هزینه‌ها و بهبود ایمنی: یک کسب‌وکار هم‌پیمایی ممکن است بخواهد مسیری را پیدا کند که هزینه کمتری برای مسافران داشته باشد و به‌دلایل ایمنی از مناطق خاصی اجتناب کند.

برای کسب اطلاعات بیشتر درباره برنامه‌ریزی مسیر بااستفاده از یک کد مسیر، به دریافت یک کد مسیر در Routes API و چندخطی‌های انتقال و کدهای مسیر در Route Optimization API مراجعه کنید.

چرا باید از کد مسیر برای اهداف مسیر استفاده کرد

بااستفاده از کد مسیر از Routes API یا Route Optimization API، کنترل بیشتری بر مسیر ارائه‌شده دارید:

مسیری را ازقبل برنامه‌ریزی کنید تا Navigation SDK از آن استفاده کند.
بهترین مسیر را برای استفاده Navigation SDK انتخاب کنید. اگر هنگام تولید مسیرها در Routes API، توکن‌های مسیر را درخواست کنید، برای هر مسیر تولیدشده یک توکن مسیر دریافت می‌کنید. سپس می‌توانید هنگام ارسال به Navigation SDK، نشان را برای مسیری که می‌خواهید استفاده کنید انتخاب کنید.
قیمت را ازقبل تخمین بزنید، ازجمله تخمین زمان تخمینی رسیدن و مسافت. اگرچه هزینه و زمان واقعی ممکن است متفاوت باشد، این تخمین فاصله بین هزینه مسیر موردانتظار و واقعی را کاهش می‌دهد.
اهداف پیشرفته‌تری برای مسیر مشخص کنید، مانند مسیریابی سازگار با محیط‌زیست یا کوتاه‌ترین مسیر.

نحوه عملکرد توکن‌های مسیر

می‌توانید از Routes API یا Route Optimization API برای برنامه‌ریزی مسیر بااستفاده از اهداف مسیر استفاده کنید. می‌توانید یک کد مسیر را که از هریک از این میاناهای برنامه‌سازی کاربردی برگردانده شده است به کیت توسعه نرم‌افزار ناوبری ارسال کنید تا نحوه مسیریابی خودرو شما را راهنمایی کند.

وقتی که یک توکن مسیر درخواست و استفاده می‌کنید، این اتفاق می‌افتد:

Routes API یا Route Optimization API یک کد رمزگذاری‌شده مسیر برمی‌گرداند که شامل چندخطی مسیر و اهداف مسیر است.
شما توکن مسیر را به کیت توسعه نرم‌افزار پیمایش ارسال می‌کنید.
کیت توسعه نرم‌افزار ناوبری، ناوبری را در مسیر برنامه‌ریزی‌شده شما شروع می‌کند، حتی اگر مسیر سریع‌تری دردسترس باشد.
درطول سفر، اگر ترافیک یا شرایط جاده تغییر کند، یا اگر خودرو از مسیر برنامه‌ریزی‌شده خارج شود، Navigation SDK مسیر جدیدی را محاسبه می‌کند که از اهداف مسیر و گزینه‌های مسیریابی تنظیم‌شده در کلید مسیر شما پیروی می‌کند.

این فرایند باعث می‌شود مسیر واقعی تا حد امکان به مسیر برنامه‌ریزی‌شده شما نزدیک باشد.

چرا ممکن است مسیر برنامه‌ریزی‌شده دقیقاً دنبال نشود

ناوبری در مسیر برنامه‌ریزی‌شده شما شروع می‌شود، اما مسیر واقعی می‌تواند در شرایطی مانند موارد زیر با آن متفاوت باشد:

وسیله نقلیه از نقطه شروع برنامه‌ریزی‌شده فاصله می‌گیرد.
ترافیک یا شرایط جاده درطول سفر تغییر کند.
خودرو از مسیر برنامه‌ریزی‌شده خارج شود.

این تفاوت‌ها می‌تواند بر مسافت، زمان تخمینی رسیدن، و دیگر ویژگی‌های مهم سفر که برای آن برنامه‌ریزی کرده‌اید تأثیر بگذارد.

برنامه‌ریزی مسیر بااستفاده از کد مسیر

می‌توانید با ایجاد یک توکن مسیر و سپس ارسال آن به Navigation SDK، مسیری را برنامه‌ریزی کنید، همان‌طور که در مراحل زیر توضیح داده شده است:

مرحله ۱: بااستفاده از Routes API یا Route Optimization API، یک نشانه مسیر ایجاد کنید

با یکی از روش‌های زیر یک توکن مسیر درخواست کنید:
- Routes API: computeRoutes. برای اطلاعات بیشتر درباره درخواست کردن توکن مسیر در Routes API، به محاسبه کردن مسیر و دریافت کردن توکن مسیر مراجعه کنید.
- Route Optimization API: optimizeTours یا batchOptimizeTours. برای اطلاعات بیشتر درباره درخواست کردن یک توکن مسیر در Route Optimization API، به چندخطی‌های انتقال و توکن‌های مسیر مراجعه کنید.
درخواست Routes API خود را راه‌اندازی کنید تا الزامات استفاده از توکن مسیر را برآورده کند:
- travelMode را روی DRIVE یا TWO_WHEELER تنظیم کنید.
- routingPreference را روی TRAFFIC_AWARE یا TRAFFIC_AWARE_OPTIMAL تنظیم کنید.
- از Via نقطه‌مسیر استفاده نکنید.

مرحله ۲: ارسال کردن توکن مسیر به Navigation SDK

ذخیره کردن کد مسیر: در «کیت توسعه نرم‌افزار پیمایش»، رشته‌ای را برای ذخیره کردن کد مسیر راه‌اندازی کنید. برای مثال:

String routeToken = "route token returned by Routes API";

نمونه‌ای از کد مسیر برگردانده‌شده:

{
// Other fields
"routeToken": "CqMBCjoKCJQOor5DHcwiEhBon3XpHXFnVvDeWMwd9PpAGgz6wtnFDKIBrAHTARpCApUDSggAAAAACjcrP3gBEAQaTApKChgKDQoCCAERAAAAAACAZkAR3SQGgZUXdUASEggAEAMQBhATEBIYAkIEGgIIBSIYChZ2VEJiWlBPSkk1aU5wUVRzNTV5d0FRKAEiFQBcJuds-Efh-2QZhOMTtUCCxEVL_g",
}

ژتون مسیر را بااستفاده از روش Navigator.setDestinationsWithToken به «کیت توسعه نرم‌افزار ناوبری» ارسال کنید. Navigation SDK مقصدها و گزینه‌های مسیریابی را از کد مسیر دریافت می‌کند، بنابراین نیازی به ارسال نقاط‌مسیر یا حالت سفر ندارید.
```
setDestinationsWithToken(String routeToken, RouteDescriptionLoadCallback callback);
setDestinationsWithToken(String routeToken, DisplayOptions displayOptions, RouteDescriptionLoadCallback callback);
```
توجه: اگر برنامه‌تان از نسخه‌ای از Navigation SDK قدیمی‌تر از ۸.۱ استفاده می‌کند، به‌جای آن از روش‌های منسوخ‌شده setDestinations که CustomRoutesOptions را می‌گیرند استفاده کنید و همان نقاط‌مسیر مقصدی را که برای ایجاد توکن مسیر استفاده کرده‌اید ارسال کنید.
وضعیت مسیر را در بازخوانی بررسی کنید. وقتی Navigation SDK محاسبه مسیر را به‌پایان می‌رساند، RouteDescription را به بازخوان شما ارسال می‌کند. اگر مسیری از مکان خودرو به مقصدهای موجود در کد مسیر شما پیدا کند، RouteDescription.getRouteStatus Navigator.RouteStatus.OK را برمی‌گرداند و می‌توانید راهنمایی را شروع کنید. برای مثال:
```
navigator.setDestinationsWithToken(
    routeToken,
    routeDescription -> {
      if (routeDescription.getRouteStatus() == Navigator.RouteStatus.OK) {
        navigator.startGuidance();
      }
    });
```

بررسی کنید که آیا Navigation SDK کد مسیر شما را اعمال کرده است یا نه

وضعیت مسیر OK یعنی Navigation SDK مسیری پیدا کرده است، اما لزوماً مسیر برنامه‌ریزی‌شده شما نیست. برای بررسی اینکه آیا مسیر با مسیر برنامه‌ریزی‌شده شما مطابقت دارد یا نه، این مراحل را در فراخوانی برگشتی خود دنبال کنید:

تأیید کنید که RouteDescription.getRouteStatus Navigator.RouteStatus.OK را برمی‌گرداند. «کیت توسعه نرم‌افزار ناوبری» جزئیات کد مسیر را فقط زمانی ارائه می‌دهد که مسیری پیدا کند. برای اطلاعات بیشتر، به مرحله ۲ مراجعه کنید.
با RouteDescription.getRouteTokenExecutionDetails تماس بگیرید تا شیء RouteTokenExecutionDetails را دریافت کنید. اگر سرور جزئیات کد مسیر را ارائه نکند، این روش null را برمی‌گرداند.
با getTokenExecutionStatus در شیء RouteTokenExecutionDetails تماس بگیرید. اگر TOKEN_SUCCESSFULLY_APPLIED را برگرداند، مسیر با مسیر برنامه‌ریزی‌شده شما مطابقت دارد. هر وضعیت دیگری به این معنی است که مسیر ممکن است با مسیر برنامه‌ریزی‌شده شما متفاوت باشد. برای اطلاعات بیشتر درباره هر وضعیت، به مقادیر وضعیت اجرای توکن مراجعه کنید.
اختیاری: اگر وضعیت TOKEN_SUCCESSFULLY_APPLIED است، getResolvedParameters را در همان شیء RouteTokenExecutionDetails فراخوانی کنید تا بررسی کنید مسیر از کدام گزینه‌های مسیریابی استفاده می‌کند، مثلاً اینکه آیا از عوارض اجتناب می‌کند یا نه. برای اطلاعات بیشتر، گزینه‌های مسیریابی حل‌شده را ببینید.

مقادیر وضعیت اجرای کد

اگر وضعیت مسیر OK باشد، می‌توانید راهنمایی را با هر وضعیت اجرای توکنی شروع کنید. وضعیت به شما می‌گوید که آیا مسیر از مسیر برنامه‌ریزی‌شده شما پیروی می‌کند یا نه.

وضعیت	مسیر برنامه‌ریزی‌شده شما را دنبال می‌کند	شرح
`TOKEN_SUCCESSFULLY_APPLIED`	بله	کیت توسعه نرم‌افزار پیمایش، کد مسیر شما را اعمال کرد.
`TOKEN_APPLIED_WITH_LOCATION_MISMATCH`	نه لزوماً	کیت توسعه نرم‌افزار ناوبری نتوانست مسیر برنامه‌ریزی‌شده شما را بازسازی کند زیرا مکانی در درخواست مسیر بیش‌از ۲۵ متر با مکان منطبق در کد مسیر شما فاصله داشت. با `setDestinationsWithToken`، این یعنی دستگاه بیش‌از ۲۵ متر از مبدأ در کد مسیر شما فاصله داشته است. مسیر همچنان به مقصدهای شما می‌رود، اما Navigation SDK نمی‌تواند تأیید کند که از گزینه‌های مسیریابی از کد مسیر شما، مانند اجتناب از عوارض، استفاده می‌کند.
`TOKEN_IGNORED_OTHER`	نه لزوماً	کیت توسعه نرم‌افزار ناوبری به‌دلیل دیگری نتوانست مسیر برنامه‌ریزی‌شده شما را بازسازی کند، مثلاً به‌دلیل بسته بودن جاده‌ای در مسیر برنامه‌ریزی‌شده شما. مسیر همچنان به مقصدهای شما می‌رود، اما Navigation SDK نمی‌تواند تأیید کند که از گزینه‌های مسیریابی از کد مسیر شما، مانند اجتناب از عوارض، استفاده می‌کند.
`NO_TOKEN_PROVIDED`	نامربوط	درخواست مسیر شامل کد مسیر نبود.
`UNKNOWN`	نامشخص	وضعیت نامشخص است.

اگر مسیر لزوماً از مسیر برنامه‌ریزی‌شده شما پیروی نمی‌کند و مسیر دقیق اهمیت دارد، برای مثال، چون از آن برای محاسبه قیمت استفاده کرده‌اید، وضعیت را ثبت کنید یا از مکان فعلی خودرو درخواست یک توکن مسیر جدید کنید.

گزینه‌های مسیریابی حل‌شده

getResolvedParameters شیء RouteTokenResolvedParameters را برمی‌گرداند، یا null اگر گزینه‌های مسیریابی دردسترس نباشد. RouteTokenResolvedParameters روش‌های زیر را دارد:

getTravelMode: حالت سفری که مسیر استفاده می‌کند، مثل RoutingOptions.TravelMode.DRIVING. همچنین، Navigation SDK RoutingOptions.TravelMode.DRIVING را زمانی گزارش می‌کند که مسیر از حالت سفری استفاده می‌کند که مقدار منطبقی ندارد، یا زمانی که حالت سفر دردسترس نیست.
getAvoidTolls: اینکه مسیر از عوارضی‌ها اجتناب می‌کند یا نه.
getAvoidHighways: اینکه مسیر از بزرگراه‌ها اجتناب می‌کند یا نه.
getAvoidFerries: اینکه مسیر از کشتی اجتناب می‌کند یا نه.

مثال

نمونه کد زیر نشان می‌دهد که چگونه بااستفاده از یک کد مسیر، مسیری را برنامه‌ریزی کنید، بررسی کنید که آیا Navigation SDK کد را اعمال کرده است یا نه، و راهنمایی را شروع کنید.

String routeToken = "route token returned by Routes API";

// Existing flow to get a Navigator.
NavigationApi.getNavigator(...);

// Handle the result of the route calculation.
RouteDescriptionLoadCallback callback =
    routeDescription -> {
      // Check whether the Navigation SDK found a route.
      if (routeDescription.getRouteStatus() != Navigator.RouteStatus.OK) {
        Log.w(TAG, "Route status: " + routeDescription.getRouteStatus());
        return;
      }

      // Check whether the Navigation SDK applied the route token.
      RouteTokenExecutionDetails executionDetails =
          routeDescription.getRouteTokenExecutionDetails();
      if (executionDetails == null) {
        Log.i(TAG, "Route token details aren't available.");
      } else if (executionDetails.getTokenExecutionStatus()
          != RouteTokenExecutionDetails.TokenExecutionStatus.TOKEN_SUCCESSFULLY_APPLIED) {
        Log.w(TAG, "The route might differ from your planned route.");
      }

      navigator.startGuidance();
    };

// Set destinations using the route token.
navigator.setDestinationsWithToken(routeToken, callback);

// Or with display options.
DisplayOptions displayOptions = new DisplayOptions();
navigator.setDestinationsWithToken(routeToken, displayOptions, callback);

نحوه تعامل نشان‌های مسیر و کیت توسعه نرم‌افزار پیمایش

نحوه مدیریت مسیر برنامه‌ریزی‌شده شما توسط Navigation SDK در اینجا توضیح داده شده است:

هر مقصد تنظیم‌شده قبلی را لغو می‌کند.
از مکان شروع خودرو استفاده می‌کند.
با شرایط جاده و ترافیک تنظیم می‌شود. ببینید چرا ممکن است مسیر برنامه‌ریزی‌شده دقیقاً دنبال نشود.

از گزینه‌های مسیریابی تنظیم‌شده در کد مسیر شما استفاده می‌کند و از تنظیمات زیر در برنامه‌تان استفاده نمی‌کند، ازجمله وقتی که مسیر جدیدی را درطول سفر محاسبه می‌کند:
- RoutingOptions.avoidHighways
- RoutingOptions.avoidTolls
- RoutingOptions.avoidFerries
- Navigator.setLicensePlateRestrictionInfo
- حالت سفر تنظیم‌شده در برنامه‌تان

هنگام محاسبه یا تنظیم مسیر، از این تنظیمات پیروی می‌کند:
- اهداف مسیر از توکن مسیر شما، مانند مسیریابی بوم‌سازگار یا کوتاه‌ترین مسیر. اگر «کیت توسعه نرم‌افزار ناوبری» مجبور به تنظیم مسیر باشد، از اهداف مسیری که هنگام درخواست کردن توکن مسیر مشخص کرده‌اید استفاده می‌کند.
- گزینه‌های مربوط به نقطه‌مسیر از شناسه مسیر شما، مانند اولویت کنار جاده.