جستجوی وسایل نقلیه

به‌عنوان بخشی از سرویس سفر «جابه‌جایی درخواستی»، می‌توانید بااستفاده از روش SearchVehicles وسایل نقلیه اطراف را پیدا کنید.

روش SearchVehicles به شما امکان می‌دهد وسایل نقلیه دردسترس در نزدیکی‌تان را در برنامه تلفن همراه مصرف‌کننده پیدا کنید که برای سفر یا درخواست تحویل خاصی مناسب‌تر هستند. میانای برنامه‌سازی کاربردی SearchVehicles فهرستی رتبه‌بندی‌شده از وسایل نقلیه برمی‌گرداند که مشخصه‌های آن‌ها با مشخصه‌های سفر درخواستی مطابقت دارد. رتبه‌بندی براساس انتخاب شما از بین زمان تخمینی رسیدن، فاصله، یا فاصله مستقیم از نقطه تحویل سفارش داده می‌شود.

جستجوی مشخصه‌ها مشخصه‌های خودرو
  • مکان‌های تحویل و پیاده کردن
  • انواع سفر و خودرو درخواست‌شده
  • ظرفیت موردنیاز
  • دیگر مشخصه‌های منطبق موردنیاز
  • آخرین مکان معلوم خودرو
  • وضعیت، نوع، یا ظرفیت وسیله نقلیه
  • دیگر مشخصه‌های سفارشی

استفاده از روش SearchVehicles

برای استفاده از SearchVehicles، این فرایند کلی را دنبال کنید:

  1. ‫SearchVehiclesRequest را براساس سفر اختصاص داده‌شده بسازید.
  2. با درخواست ساخته‌شده، SearchVehicles API (vehicleService.searchVehicles) را فراخوانی کنید.
  3. SearchVehicleResponse برگشتی از API را پردازش کنید.

فیلدهای SearchVehiclesRequest

از فیلدهای مشخصه الزامی زیر برای ساختن SearchVehiclesRequest استفاده کنید:

فیلد شرح
ولی الزامی. باید در قالب providers/{provider} باشد. ارائه‌دهنده باید «شناسه پروژه» Google Cloud Project باشد که حساب سرویسِ برقرارکننده این تماس عضو آن است.
vehicle_types الزامی. انواع وسایل نقلیه درخواستی، یا AUTO، TWO_WHEELER، TAXI، TRUCK، BICYCLE، یا PEDESTRIAN.
trip_types الزامی. یا «انحصاری» (هر راننده در هر زمان یک سفر فعال دارد) یا «اشتراکی» (هر راننده در هر زمان یک یا چند سفر دارد).
minimum_capacity الزامی. حداقل ظرفیت باقی‌مانده خودرو برای سفر جدید، چه برای مسافر و چه برای ارسال.
pickup_point الزامی. مکان سوار شدن در سفر با مختصات طول/عرض جغرافیایی.
dropoff_point اختیاری. مکان پیاده شدن سفر در مختصات عرض/طول جغرافیایی. اگر trip_types حاوی TripType.SHARED باشد، این فیلد الزامی است.
pickup_radius_meters الزامی. شعاع محل جستجوی خودرو از نقطه سوار شدن به متر.
order_by الزامی. خودروها را براساس یکی از موارد زیر مرتب کنید:
  • PICKUP_POINT_ETA، زمان تخمینی رسیدن خودرو به نقطه سوار کردن.
  • PICKUP_POINT_DISTANCE، فاصله بین خودرو و نقطه سوار کردن.
  • ‫DROPOFF_POINT_ETA، زمان تخمینی رسیدن خودرو برای تکمیل سفر در نقطه پیاده کردن.
  • PICKUP_POINT_STRAIGHT_DISTANCE، فاصله مستقیم (نه در مسیر) بین خودرو و نقطه سوار کردن.
تعداد الزامی. حداکثر تعداد وسایل نقلیه برای برگشتن از ۱ تا ۵۰.
فیلتر کردن اختیاری. پُرسمان فیلتری که هنگام جستجوی وسایل نقلیه اعمال می‌شود.
maximum_staleness اختیاری. جستجو را به خودروهایی محدود می‌کند که به‌روزرسانی‌های مکان را در مدت زمان مشخص‌شده به Fleet Engine ارسال کرده‌اند. اگر این فیلد تنظیم نشده باشد، سرور از پنج دقیقه به‌عنوان مقدار پیش‌فرض استفاده می‌کند.

برای دیدن مجموعه کامل فیلدهای SearchVehicleRequest، به «مستندات مرجع» مراجعه کنید.

سناریوهای SearchVehiclesRequest

این بخش نمونه‌هایی از نحوه ساخت SearchVehiclesRequest را نشان می‌دهد.

برای مثال، فرض کنید مشتری می‌خواهد در «رستوران X» سوار شود، و شما چهار وسیله نقلیه دارید:

  • خودرو ۱: ۳۵۰۰ متر دورتر از «رستوران X».
  • خودرو ۲: ۱۰۰ متر دورتر از RestaurantX با سفر فعال با سوار کردن و پیاده کردن در مکان‌های الف و ب.
  • خودروی ۳: ۲۰۰ متر دورتر از RestaurantX با یک توقف باقی‌مانده در فاصله‌ای بسیار دور.
  • خودرو ۴: ۱۰۰۰ متر دورتر از «رستوران X».

در زیر درخواست‌های مختلف براساس خودرویی که برمی‌گردانند نمایش داده شده است.

برگشت خودرو ۴

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA

«خودرو ۳» و «خودرو ۴» را برمی‌گرداند

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, is_back_to_back enabled

خودرو ۲، ۳، و ۴ را برمی‌گرداند

     Pickup at RestaurantX, radius = 1200m, order by PICKUP_POINT_ETA, current_trips_present = ALL

فیلدهای SearchVehiclesResponse

SearchVehiclesResponse شامل فهرستی از نهادهای VehicleMatch است که براساس مشخصه order_by تعیین‌شده در SearchVehiclesRequest رتبه‌بندی شده‌اند. هر نهاد VehicleMatch فیلدهای زیر را دارد:

فیلد شرح
وسیله نقلیه شیء Vehicle، شامل vehicle_id و مشخصه‌های Vehicle.
vehicle_pickup_eta زمان تخمینی رسیدن خودرو به مکان سوار کردن مسافر درصورتی‌که این سفر همین حالا به خودرو واگذار شود.
vehicle_pickup_distance_meter فاصله برحسب متر بین خودرو و مکان سوار شدن سفر جدید.
vehicle_pickup_straight_line_distance_meter فاصله مستقیم برحسب متر بین خودرو و مکان تحویل سفر جدید.
vehicle_dropoff_eta زمان تخمینی رسیدن خودرو به مکان پیاده کردن مسافر درصورتی‌که این سفر همین حالا به خودرو اختصاص داده شود.
vehicle_trips_waypoints فهرستی از نقاط‌مسیر باقی‌مانده، ازجمله نقاط سوار کردن و پیاده کردن، برای سفرهای فعالی که درحال‌حاضر به خودرو اختصاص داده شده‌اند.
vehicle_match_type نوع سفر خودرو، که می‌تواند EXCLUSIVE،‏ BACK_TO_BACK،‏ CARPOOL، یا CARPOOL_BACK_TO_BACK باشد.

برای فهرست کامل فیلدهای VehicleMatch، به این نشانی مراجعه کنید:

استفاده از پرسمان‌های فیلتر

SearchVehicles و ListVehicles از فیلتر کردن براساس مشخصه‌های خودرو بااستفاده از پرسمان فیلتر پشتیبانی می‌کنند.

پُرسمان‌های فیلتر فقط از فیلتر کردن براساس مشخصه‌های سفارشی برای خودروها پشتیبانی می‌کنند و نمی‌توان از آن‌ها برای فیلدهای دیگر استفاده کرد. وقتی در جستجویی استفاده شود که شامل معیارهای فیلد دیگری، مثل minimum_capacity یا vehicle_types، باشد، پُرسمان فیلتر به‌عنوان عبارت AND عمل می‌کند.

برای مثال، اگر خودرویی را جستجو کنید که حداقل ظرفیت آن ۶ نفر باشد و فیلتر attributes مثل «امکان همراه داشتن حیوان خانگی» را اعمال کنید، معیارهای شما فقط خودروهایی را برمی‌گرداند که هم امکان همراه داشتن حیوان خانگی را داشته باشند و هم بتوانند حداقل ۶ مسافر را حمل کنند.

برای نحو پرسمان فیلتر، به AIP-160 برای نمونه‌ها مراجعه کنید. برای جزئیات مربوط به ایجاد مشخصه‌های خودرو، فیلد مشخصه‌های خودرو را در راهنمای به‌روزرسانی فیلدهای خودرو ببینید.

نمونه SearchVehicles

مثال زیر نحوه استفاده از SearchVehicles API را بااستفاده از کتابخانه Java gRPC نشان می‌دهد. برای فهرست کامل زبان‌های پشتیبانی‌شده، به کتابخانه‌های مشتری برای خدمات سفر درخواستی مراجعه کنید.

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jkt Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(Category.AUTO).build())
    .setCurrentTripsPresent(CurrentTripsPresent.ANY)
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .build();

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

List<VehicleMatch> vehicleMatches =
    searchVehicleResponse.getMatchesList();

// Each VehicleMatch contains a Vehicle entity and information about the
// distance and ETA to the pickup point and drop-off point.

قدم بعدی چیست