شروع کار با Fleet Engine، شروع به کار با Fleet Engine

Fleet Engine On-Deman Rides and Deliveries API به شما امکان می دهد سفرها و وضعیت خودرو را برای برنامه های کاربردی سفر و پیشرفت سفارش خود مدیریت کنید. این تراکنش‌های بین Driver SDK، Consumer SDK و سرویس پشتیبان شما را مدیریت می‌کند - که می‌تواند با برقراری تماس‌های gRPC یا REST با Fleet Engine ارتباط برقرار کند.

پیش نیازها

برای توسعه، مطمئن شوید که Cloud SDK (gcloud) را نصب کرده اید و در پروژه خود احراز هویت شده اید.

پوسته

gcloud auth login

شما باید یک پیام موفقیت آمیز مانند:

You are now logged in as [my-user@example.com].
Your current project is [project-id].  You ...

بررسی کنید که APIهای موتور ناوگان راه‌حل‌های سفارشی و تحویل به‌طور مناسب پیکربندی شده باشند.

پوسته

gcloud --project=project-id services enable fleetengine.googleapis.com

اگر این دستور منجر به خطا شد، برای دسترسی با سرپرست پروژه و نماینده پشتیبانی Google خود تماس بگیرید.

ورود به سیستم

Fleet Engine می‌تواند پیام‌های گزارشی را درباره تماس‌های API که دریافت می‌کند در گزارش‌های پلتفرم Google Cloud بنویسد. برای مروری بر نحوه خواندن و تجزیه و تحلیل گزارش‌ها، به مستندات Cloud Logging مراجعه کنید.

گزارش‌گیری ممکن است به‌طور پیش‌فرض برای پروژه‌هایی که قبل از 10 فوریه 2022 ایجاد شده‌اند فعال نباشد. برای جزئیات بیشتر به اسناد گزارش‌گیری مراجعه کنید.

کتابخانه های مشتری

ما کتابخانه های مشتری را در چندین زبان برنامه نویسی رایج منتشر می کنیم. این کتابخانه ها به ارائه تجربه بهتر توسعه دهنده نسبت به REST خام یا gRPC کمک می کنند. برای دستورالعمل‌های نحوه به‌دست آوردن کتابخانه‌های سرویس گیرنده برای برنامه سرور خود، به کتابخانه‌های مشتری مراجعه کنید.

مثال‌های جاوا در این مستندات، آشنایی با gRPC را فرض می‌کنند.

احراز هویت و مجوز

می‌توانید قابلیت‌های ارائه شده توسط Trip and Order Progress را از طریق Google Cloud Console پیکربندی کنید. این APIها و SDKها نیاز به استفاده از نشانه‌های وب JSON دارند که با استفاده از حساب‌های سرویس ایجاد شده از کنسول Cloud امضا شده‌اند.

راه اندازی پروژه ابری

برای راه اندازی پروژه ابری خود، ابتدا پروژه خود را ایجاد کنید و سپس حساب های خدماتی ایجاد کنید.

برای ایجاد پروژه Google Cloud:

  1. با استفاده از Google Cloud Console یک پروژه Google Cloud ایجاد کنید.
  2. با استفاده از API ها و داشبورد خدمات، API Local Rides and Deliveries را فعال کنید.

حساب‌های سرویس با یک یا چند نقش مرتبط هستند. آنها برای ایجاد توکن های وب JSON استفاده می شوند که بسته به نقش ها مجموعه های مختلفی از مجوزها را می دهند. به طور معمول، برای کاهش احتمال سوء استفاده، می توانید چندین حساب سرویس ایجاد کنید که هر کدام دارای حداقل مجموعه ای از نقش های مورد نیاز هستند.

Trip and Order Progress از نقش های زیر استفاده می کند:

نقش شرح
کاربر SDK مصرف کننده موتور ناوگان

roles/fleetengine.consumerSdkUser		 اجازه جستجوی وسایل نقلیه و بازیابی اطلاعات مربوط به وسایل نقلیه و سفرها را می دهد. نشانه‌هایی که توسط یک حساب سرویس با این نقش ایجاد می‌شوند، معمولاً از دستگاه‌های تلفن همراه برنامه مصرف‌کننده اشتراک‌گذاری یا تحویل شما استفاده می‌شوند.
کاربر SDK درایور موتور ناوگان

roles/fleetengine.driverSdkUser		 اجازه به‌روزرسانی مکان‌ها و مسیرهای خودرو و بازیابی اطلاعات مربوط به وسایل نقلیه و سفرها را می‌دهد. نشانه‌هایی که توسط یک حساب سرویس با این نقش ایجاد می‌شوند، معمولاً از دستگاه‌های تلفن همراه برنامه راننده اشتراک‌گذاری یا تحویل شما استفاده می‌شوند.
کاربر فوق العاده خدمات موتور ناوگان

roles/fleetengine.serviceSuperUser		 به همه APIهای وسایل نقلیه و سفرها مجوز می دهد. توکن‌هایی که توسط یک حساب سرویس با این نقش ایجاد می‌شوند، معمولاً از سرورهای پشتیبان شما استفاده می‌شوند.

به عنوان مثال، برای هر یک از سه نقش یک حساب کاربری ایجاد کنید و نقش های مربوطه را به آنها اختصاص دهید.

gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.consumerSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.driverSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-su
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.serviceSuperUser

Driver و Consumer SDK بر اساس این نقش های استاندارد ساخته شده اند.

از طرف دیگر، امکان ایجاد نقش‌های سفارشی وجود دارد که اجازه می‌دهد مجموعه‌ای دلخواه از مجوزها با هم جمع شوند. هر زمان که مجوز لازم وجود نداشته باشد، Driver و Consumer SDK پیام‌های خطا نشان می‌دهند. در نتیجه، ما قویاً توصیه می کنیم از مجموعه استاندارد نقش های ارائه شده در بالا استفاده کنید و از نقش های سفارشی استفاده نکنید.

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

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

جایی که my-user@example.com ایمیلی است که برای احراز هویت با gcloud استفاده می‌شود ( gcloud auth list --format='value(account)' ).

کتابخانه تأیید موتور ناوگان

Fleet Engine از JSON Web Tokens (JWTs) برای محدود کردن دسترسی به APIهای Fleet Engine استفاده می کند. کتابخانه جدید Fleet Engine Auth که در Github موجود است ، ساخت JWTهای Fleet Engine را ساده کرده و آنها را به صورت ایمن امضا می کند.

این کتابخانه دارای مزایای زیر است:

  • فرآیند ایجاد توکن های Fleet Engine را ساده می کند.
  • مکانیسم‌های امضای رمز را به غیر از استفاده از فایل‌های اعتبار (مانند جعل هویت یک حساب سرویس) ارائه می‌کند.
  • توکن‌های امضا شده را به درخواست‌های خروجی که از یک کاربر خرد gRPC یا GAPIC ارسال شده است، پیوست می‌کند.

ایجاد یک توکن وب JSON (JWT) برای مجوز

وقتی از کتابخانه تأیید موتور Fleet استفاده نمی‌کنید، توکن‌های وب JSON (JWT) باید مستقیماً در پایگاه کد شما ایجاد شوند. این امر مستلزم آن است که هم درک عمیقی از JWT ها و هم ارتباط آنها با Fleet Engine داشته باشید. به همین دلیل است که ما به شدت توصیه می کنیم از کتابخانه تأیید موتور ناوگان استفاده کنید.

در Fleet Engine، JSON Web Tokens (JWT) احراز هویت کوتاه مدت را ارائه می‌کند و اطمینان می‌دهد که دستگاه‌ها فقط می‌توانند وسایل نقلیه، سفرها یا کارهایی را که برای آنها مجاز هستند تغییر دهند. JWT ها شامل یک هدر و یک بخش ادعا هستند. بخش هدر حاوی اطلاعاتی مانند کلید خصوصی برای استفاده (به دست آمده از حساب های سرویس) و الگوریتم رمزگذاری است. بخش ادعا حاوی اطلاعاتی مانند زمان ایجاد رمز، زمان زنده ماندن نشانه‌ها، خدماتی است که ادعای دسترسی به آنها را دارد و سایر اطلاعات مجوز برای محدود کردن دسترسی. برای مثال شناسه وسیله نقلیه

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

رشته شرح
alg الگوریتم مورد استفاده "RS256".
تایپ کنید نوع توکن "JWT".
بچه شناسه کلید خصوصی حساب سرویس شما. می‌توانید این مقدار را در قسمت «private_key_id» فایل JSON حساب سرویس خود بیابید. اطمینان حاصل کنید که از یک کلید از یک حساب سرویس با سطح صحیح مجوز استفاده می کنید.

بخش ادعاهای JWT شامل فیلدهای زیر است:

رشته شرح
iss آدرس ایمیل حساب سرویس شما.
زیر آدرس ایمیل حساب سرویس شما.
aud SERVICE_NAME حساب سرویس شما، در این مورد https://fleetengine.googleapis.com/
iat مُهر زمانی که نشانه ایجاد شد، برحسب ثانیه های سپری شده از ساعت 00:00:00 UTC، 1 ژانویه 1970 مشخص شده است. برای انحراف 10 دقیقه زمان بگذارید. اگر مهر زمانی در گذشته یا در آینده خیلی دور باشد، سرور ممکن است خطا را گزارش کند.
انقضا مهر زمانی که نشان منقضی می‌شود، برحسب ثانیه مشخص شده است که از ساعت 00:00:00 UTC، 1 ژانویه 1970 سپری شده است. اگر مهر زمانی بیش از یک ساعت در آینده باشد، درخواست انجام نمی‌شود.
مجوز بسته به مورد استفاده، ممکن است حاوی «vehicleid» یا «tripid» باشد.

ایجاد یک توکن JWT به امضای آن اشاره دارد. برای دستورالعمل‌ها و نمونه‌های کد برای ایجاد و امضای JWT، به مجوز حساب سرویس بدون OAuth مراجعه کنید. سپس می‌توانید یک نشانه امضا شده را به تماس‌های gRPC یا سایر روش‌های مورد استفاده برای دسترسی به Fleet Engine متصل کنید.

ادعاهای JWT

هنگام ایجاد محموله JWT، یک ادعای اضافی در بخش مجوز با کلید vehicleid یا tripid تنظیم شده به ارزش شناسه وسیله نقلیه یا شناسه سفری که تماس برای آن برقرار شده است، اضافه کنید.

Driver SDK همیشه از ادعای vehicleid استفاده می کند، خواه در سفر یا وسیله نقلیه کار کند. بخش پشتیبان Fleet Engine اطمینان می دهد که وسیله نقلیه قبل از انجام اصلاحات با سفر درخواستی مرتبط است.

Consumer SDK همیشه از ادعای tripid استفاده می کند.

ارائه دهنده Rideshare یا Delivery باید از vehicleid یا tripid با یک "*" برای مطابقت با تمام وسایل نقلیه و سفرها استفاده کند. توجه داشته باشید که JWT می‌تواند حاوی هر دو نشانه باشد، حتی اگر مورد نیاز نباشد، که ممکن است اجرای امضای توکن را ساده‌تر کند.

موارد استفاده JWT

شکل زیر یک نمونه توکن برای سرور ارائه دهنده را نشان می دهد:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_provider_service_account"
}
.
{
  "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
  "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

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

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

شکل زیر نمونه ای از نشانه برای برنامه Driver را نشان می دهد:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}
  • برای فیلد kid در هدر، شناسه کلید خصوصی حساب سرویس خود را مشخص کنید. می توانید این مقدار را در قسمت private_key_id فایل JSON حساب سرویس خود بیابید.
  • برای فیلدهای iss و sub ، آدرس ایمیل حساب سرویس خود را مشخص کنید. می توانید این مقدار را در قسمت client_email فایل JSON حساب سرویس خود بیابید.
  • برای قسمت aud ، https://SERVICE_NAME/ را مشخص کنید.
  • برای فیلد iat ، از مهر زمانی هنگام ایجاد نشانه استفاده کنید، که به عنوان ثانیه های سپری شده از ساعت 00:00:00 UTC، 1 ژانویه 1970 مشخص شده است. 10 دقیقه برای انحراف زمان بگذارید. اگر مهر زمانی در گذشته یا در آینده خیلی دور باشد، سرور ممکن است خطا را گزارش کند.
  • برای فیلد exp ، از مهر زمانی زمانی که نشانه منقضی می‌شود استفاده کنید، که به عنوان ثانیه از ساعت 00:00:00 UTC، 1 ژانویه 1970 مشخص شده است. حداکثر مقدار مجاز iat + 3600 است.

هنگام امضای JWT برای انتقال به دستگاه تلفن همراه، مطمئن شوید که از حساب سرویس برای نقش Driver یا Consumer SDK استفاده می‌کنید. در غیر این صورت، دستگاه تلفن همراه توانایی تغییر حالتی را که نباید داشته باشد خواهد داشت.

به همین ترتیب، هنگام امضای JWT برای استفاده برای تماس‌های ممتاز، مطمئن شوید که از حساب سرویس با نقش Super User استفاده می‌کنید. در غیر این صورت، عملیات شکست خواهد خورد.

تولید JWT برای آزمایش

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

برای انجام این مراحل، حساب کاربری شما باید نقش ایجاد کننده رمز حساب کاربری را داشته باشد:

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

یک فایل جدید به نام unsigned_token.json با محتوای زیر ایجاد کنید. ویژگی iat زمان فعلی بر حسب ثانیه بعد از دوره است که با اجرای date +%s در ترمینال شما قابل بازیابی است. ویژگی exp زمان انقضا بر حسب ثانیه بعد از دوره است که با افزودن 3600 به iat قابل محاسبه است. زمان انقضا در آینده نمی تواند بیش از یک ساعت باشد.

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "sub": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

سپس دستور gcloud زیر را اجرا کنید تا رمز را از طرف حساب سرویس Super User خود امضا کنید:

gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt

اکنون یک JWT رمزگذاری شده با Base64 امضا شده باید در فایل signed_token.jwt ذخیره شود. ژتون برای یک ساعت بعد معتبر است.

اکنون می توانید توکن را با اجرای دستور curl در مقابل نقطه پایانی List Vehicles REST آزمایش کنید:

curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"

وسایل نقلیه و چرخه حیات آنها

Vehicle نهادی است که یک جفت راننده و وسیله نقلیه را نشان می دهد. در حال حاضر، راننده و وسیله نقلیه را نمی توان به طور جداگانه ردیابی کرد. ارائه‌دهنده Rideshare یا Delivery با استفاده از شناسه ارائه‌دهنده (که باید همان شناسه پروژه Google Cloud Project که حاوی حساب سرویس مورد استفاده برای فراخوانی APIهای Fleet Engine است) و یک شناسه خودرو متعلق به ارائه‌دهنده Rideshare یا تحویل‌دهنده باشد، وسیله نقلیه ایجاد می‌کند. .

خودرویی که پس از هفت روز از طریق UpdateVehicle به‌روزرسانی نشده باشد، به‌طور خودکار حذف می‌شود. فراخوانی CreateVehicle با یک جفت شناسه ارائه دهنده/شناسه وسیله نقلیه که از قبل وجود دارد یک خطا است. موارد وسایل نقلیه‌ای که اغلب به‌روزرسانی نمی‌شوند را می‌توان به دو روش بررسی کرد: تماس مکرر CreateVehicle با یک جفت شناسه ارائه‌دهنده/شناسه وسیله نقلیه مورد انتظار و حذف خطا در صورتی که خودرو از قبل وجود داشته باشد. یا، فراخوانی CreateVehicle پس از بازگشت UpdateVehicle با خطای NOT_FOUND .

به روز رسانی مکان خودرو

برای بهترین عملکرد با Fleet Engine، جریانی از به‌روزرسانی‌های مکان خودرو را در اختیار آن قرار دهید. برای ارائه این به روز رسانی ها از یکی از راه های زیر استفاده کنید:

  1. از Driver SDK - Android ، iOS - ساده ترین گزینه استفاده کنید.
  2. از کد سفارشی استفاده کنید -- اگر مکان‌ها از طریق باطن شما منتقل می‌شوند یا اگر از دستگاه‌هایی غیر از Android یا iOS استفاده می‌کنید مفید است.

انواع وسایل نقلیه

موجودیت وسیله نقلیه حاوی یک فیلد الزامی از VehicleType است که حاوی یک فهرست Category است که می تواند به عنوان AUTO ، TAXI ، TRUCK ، TWO_WHEELER ، BICYCLE یا PEDESTRIAN مشخص شود. نوع وسیله نقلیه می تواند به عنوان یک معیار فیلتر در SearchVehicles و ListVehicles عمل کند.

اگر دسته روی AUTO , TWO_WHEELER , BICYCLE یا PEDESTRIAN تنظیم شده باشد , همه مسیریابی برای وسایل نقلیه از RouteTravelMode مربوطه استفاده خواهد کرد . اگر دسته روی TAXI یا TRUCK تنظیم شود، مسیریابی مانند حالت AUTO رفتار می شود.

ویژگی های خودرو

نهاد Vehicle حاوی یک فیلد مکرر از VehicleAttribute است. این ویژگی ها توسط Fleet Engine تفسیر نمی شوند. SearchVehicles API شامل فیلدی است که الزام می‌کند Vehicles منطبق باید شامل تمام ویژگی‌های موجود در مقدار مشخص شده باشند.

توجه داشته باشید که فیلد مشخصه علاوه بر چندین فیلد پشتیبانی شده دیگر در پیام Vehicle است، مانند vehicle_type و supported_trip_types .

ایستگاه های راه باقی مانده وسیله نقلیه

موجودیت وسیله نقلیه حاوی یک فیلد مکرر از TripWaypoint ( RPC | REST ) ​​است که waypoints ( RPC | REST ) ​​نامیده می شود. این فیلد به ترتیبی که وسیله نقلیه به آنها می رسد، نقاط بین راه را در سفرها شامل می شود. Fleet Engine این فیلد را زمانی که سفرها به وسیله نقلیه اختصاص می‌یابد محاسبه می‌کند و با تغییر وضعیت سفرها، آن را به‌روزرسانی می‌کند. این نقاط را می توان با فیلد TripId و فیلد WaypointType شناسایی کرد.

گسترش واجد شرایط بودن یک وسیله نقلیه برای مسابقات

به طور معمول، خدمات Rideshare یا Delivery Provider مسئول مطابقت درخواست‌های سفر با وسایل نقلیه است. این سرویس می تواند از ویژگی های خودرو برای گنجاندن یک وسیله نقلیه در تعداد بیشتری از جستجوها استفاده کند. برای مثال، ارائه‌دهنده می‌تواند مجموعه‌ای از ویژگی‌های مربوط به سطوح امتیازات یا قابلیت‌های ارائه‌شده توسط یک وسیله نقلیه را پیاده‌سازی کند. به عنوان مثال، سه سطح می تواند مجموعه ای از ویژگی ها با مقادیر بولی باشد: is_bronze_level ، is_silver_level و is_gold_level . یک وسیله نقلیه می تواند برای هر سه واجد شرایط باشد. هنگامی که Fleet Engine درخواستی برای سفری دریافت می کند که به قابلیت های سطح نقره ای نیاز دارد، جستجو شامل آن وسیله نقلیه می شود. استفاده از ویژگی ها از این طریق شامل وسایل نقلیه ای می شود که قابلیت های مختلفی را ارائه می دهند.

دو راه برای به روز رسانی ویژگی های خودرو وجود دارد. یکی UpdateVehicle API است. هنگام استفاده از این API، کل مجموعه ویژگی های خودرو روی مقدار تنظیم می شود. امکان به روز رسانی یک ویژگی واحد وجود ندارد. روش دیگر UpdateVehicleAttributes API است. این روش فقط ویژگی هایی را برای به روز رسانی می گیرد. ویژگی های گنجانده شده در درخواست به مقدار جدید تنظیم می شود یا اضافه می شود. ویژگی های نامشخص تغییر نخواهند کرد.

چگونه: یک وسیله نقلیه بسازید

برای ردیابی هر خودرو در ناوگان باید یک نهاد Vehicle ایجاد شود.

از نقطه پایانی CreateVehicle با CreateVehicleRequest برای ایجاد یک وسیله نقلیه استفاده کنید.

provider_id Vehicle باید شناسه پروژه (به عنوان مثال پروژه my-on-demand-پروژه) Google Cloud باشد که حاوی حساب‌های خدماتی است که برای فراخوانی Fleet Engine استفاده می‌شود. توجه داشته باشید که اگرچه چندین حساب خدمات ممکن است به Fleet Engine برای یک Rideshare یا Delivery Provider دسترسی داشته باشند، Fleet Engine در حال حاضر از حساب‌های خدماتی از چندین پروژه Google Cloud که به یک Vehicles دسترسی دارند پشتیبانی نمی‌کند.

Vehicle می توان در حالت OFFLINE یا ONLINE ایجاد کرد. در صورت ایجاد ONLINE ممکن است فوراً در پاسخ به سؤالات SearchVehicles برگردانده شود.

ممکن است یک last_location اولیه در تماس CreateVehicle گنجانده شود. در حالی که مجاز است، یک Vehicle نباید در حالت ONLINE بدون last_location ایجاد شود.

برای جزئیات بیشتر در مورد فیلد نوع خودرو به انواع خودرو مراجعه کنید.

برای جزئیات بیشتر در مورد فیلد ویژگی ها به ویژگی های خودرو مراجعه کنید.

مقدار بازگشتی از CreateVehicle ، موجودیت Vehicle ایجاد شده است.

مثال

پوسته

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "OFFLINE",
    "supportedTripTypes": ["EXCLUSIVE"],
    "maximumCapacity": 4,
    "vehicleType": {"category": "AUTO"},
    "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

مرجع ارائه دهنده ها.خودروها.ایجاد مرجع را ببینید.

جاوا

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.OFFLINE)  // Initial state
    .addSupportedTripTypes(TripType.EXCLUSIVE)
    .setMaximumCapacity(4)
    .setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .addAttributes(VehicleAttribute.newBuilder()
        .setKey("on_trip").setValue("false"))  // Opaque to the Fleet Engine
    // Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
    // matching while even if it is on a trip.  By default this is disabled.
    .build();

CreateVehicleRequest createVehicleRequest =
    CreateVehicleRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setVehicleId("vid-8241890")  // Vehicle ID assigned by Rideshare or Delivery Provider
        .setVehicle(vehicle)  // Initial state
        .build();

// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided.  When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.

try {
  Vehicle createdVehicle =
      vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle created successfully.

گزارش‌های پلتفرم Google Cloud برای ایجاد خودرو

هنگامی که تماسی با نقطه پایانی CreateVehicle دریافت می‌شود، Fleet Engine API یک ورودی گزارش از طریق گزارش‌های پلتفرم Google Cloud می‌نویسد. ورودی گزارش شامل اطلاعاتی در مورد مقادیر در درخواست CreateVehicle است. در صورت موفقیت آمیز بودن تماس، اطلاعات مربوط به Vehicle برگشت داده شده را نیز شامل می شود.

پوسته

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'

باید رکوردی مشابه موارد زیر چاپ کنید:

---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
  '@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
  request:
    vehicle:
      attributes:
      - key: on_trip
        value: 'false'
      maximumCapacity: 4
      state: VEHICLE_STATE_OFFLINE
      supportedTrips:
      - EXCLUSIVE_TRIP
      vehicleType:
        vehicleCategory: AUTO
    vehicleId: vid-8241890
  response:
    attributes:
    - key: on_trip
      value: 'false'
    availableCapacity: 4
    currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
    maximumCapacity: 4
    name: providers/project-id/vehicles/vid-8241890
    state: VEHICLE_STATE_OFFLINE
    supportedTrips:
    - EXCLUSIVE_TRIP
    vehicleType:
      vehicleCategory: AUTO
labels:
  vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
  labels:
    location: global
    resource_container: projects/project-id
  type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'

اعلان‌های Cloud Pub/Sub برای ایجاد خودرو

Fleet Engine API یک اعلان از طریق Cloud Pub/Sub هنگام ایجاد یک وسیله نقلیه جدید منتشر می کند. برای دریافت این اعلان‌ها، لطفاً دستورالعمل‌های اینجا را دنبال کنید.

نحوه انجام: به روز رسانی مکان وسیله نقلیه

اگر از Driver SDK برای به‌روزرسانی مکان خودرو استفاده نمی‌کنید، می‌توانید با مکان خودرو مستقیماً با Fleet Engine تماس بگیرید. برای هر وسیله نقلیه فعال، Fleet Engine انتظار دارد حداقل یک بار در هر دقیقه و حداکثر یک بار در هر 5 ثانیه یک به روز رسانی مکان انجام شود. این به‌روزرسانی‌ها فقط به امتیازات کاربر Fleet Engine Driver SDK نیاز دارند.

مثال

پوسته

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
}
EOM

مرجع providers.vehicles.update را ببینید.

جاوا

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setLastLocation(VehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("last_location"))
    .build();

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

نحوه انجام: سایر فیلدهای خودرو را به روز کنید

به‌روزرسانی سایر ویژگی‌های حالت خودرو کمتر از به‌روزرسانی‌های موقعیت رخ می‌دهد. به‌روزرسانی ویژگی‌های غیر از last_location به امتیازات Fleet Engine Super User نیاز دارد.

UpdateVehicleRequest شامل یک update_mask است که نشان می دهد کدام فیلدها باید به روز شوند. رفتار میدان مانند مستندات Protobuf برای ماسک های میدان است.

همانطور که در Vehicle Attributes اشاره شد، به‌روزرسانی فیلد attributes مستلزم نوشتن تمام ویژگی‌ها است تا حفظ شود. در تماس UpdateVehicle نمی توان فقط مقدار یک جفت کلید-مقدار را به روز کرد. برای به‌روزرسانی مقادیر مشخصه‌های خاص، می‌توان از UpdateVehicleAttributes API استفاده کرد.

مثال

این مثال back_to_back فعال می کند.

پوسته

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "ONLINE",
    "attributes": [
      {"key": "on_trip", "value": "true"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

مرجع providers.vehicles.update را ببینید.

جاوا

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.ONLINE)
    .addAllAttributes(ImmutableList.of(
        VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
        VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
    .setBackToBackEnabled(true)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_state")
        .addPaths("attributes")
        .addPaths("back_to_back_enabled"))
    .build();

// Attributes and vehicle state are being updated, so both are
// included in the field mask.  Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

گزارش‌های پلتفرم Google Cloud برای به‌روزرسانی‌های خودرو

هنگامی که تماسی با نقطه پایانی UpdateVehicle دریافت می‌شود، Fleet Engine API یک ورودی گزارش از طریق گزارش‌های پلتفرم Google Cloud می‌نویسد. ورودی گزارش شامل اطلاعاتی در مورد مقادیر در درخواست UpdateVehicle است. در صورت موفقیت آمیز بودن تماس، اطلاعات مربوط به Vehicle برگشت داده شده را نیز شامل می شود.

پوسته

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'

اعلان‌های Cloud Pub/Sub برای به‌روزرسانی‌های خودرو

Fleet Engine API یک اعلان از طریق Cloud Pub/Sub هنگامی که یک وسیله نقلیه موجود به روز می شود منتشر می کند. برای دریافت این اعلان‌ها، لطفاً دستورالعمل‌های اینجا را دنبال کنید.

روش: وسایل نقلیه را جستجو کنید

Fleet Engine از جستجوی وسایل نقلیه پشتیبانی می کند. SearchVehicles API به شما امکان می دهد درایورهای موجود در نزدیکی را بیابید که برای کارهایی مانند سرویس یک سواری یا درخواست تحویل مناسب هستند. SearchVehicles API فهرست رتبه بندی شده ای از رانندگان را برمی گرداند که ویژگی های وظیفه را با ویژگی های وسایل نقلیه در ناوگان شما مطابقت می دهند. برای اطلاعات بیشتر، به یافتن درایورهای نزدیک مراجعه کنید.

مثال

هنگام جستجوی وسایل نقلیه موجود، Fleet Engine به طور پیش فرض وسایل نقلیه در سفرهای فعال را حذف می کند. خدمات Rideshare یا Delivery Provider باید به صراحت آنها را در درخواست های جستجو لحاظ کند. مثال زیر نشان می‌دهد که چگونه می‌توان آن وسایل نقلیه را در جستجوی وسایل نقلیه منطبق با سفر از مرکز خرید بزرگ اندونزی شرقی به مرکز همایش Balai Sidang جاکارتا گنجاند.

پوسته

ابتدا مکان وسیله نقلیه ای را که در مراحل قبلی ایجاد کردیم به روز کنید تا واجد شرایط باشد. در دنیای واقعی، این کار توسط Driver SDK که روی دستگاه اندروید یا iOS در خودرو اجرا می‌شود، انجام می‌شود.

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
    "location": {
      "latitude": "-6.195139",
      "longitude": "106.820826"
    }
  },
  "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

انجام جستجو باید حداقل آن وسیله نقلیه را به دست آورد.

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  },
  "pickupRadiusMeters": 2000,
  "count": 10,
  "minimumCapacity": 2,
  "tripTypes": ["EXCLUSIVE"],
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
  "orderBy": "PICKUP_POINT_ETA",
  "includeBackToBack": true
}
EOM

مرجع providers.vehicles.search را ببینید.

جاوا

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 Jakarta 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(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);

  // Search results: Each vehicle match contains a vehicle entity and information
  // about the distance and ETA to the pickup point and dropoff point.
  List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

پرس و جو فیلترینگ خودرو

SearchVehicles و ListVehicles از فیلتر کردن ویژگی‌های خودرو با استفاده از جستجوی فیلتر پشتیبانی می‌کنند. برای نحو پرس و جو فیلتر، برای مثال AIP-160 را ببینید.

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

نحوه: لیست وسایل نقلیه

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

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

برای فیلتر کردن ویژگی‌های خودرو، لطفاً به جستار فیلترینگ خودرو مراجعه کنید.

مثال

این مثال فیلتر کردن vehicle_type و ویژگی ها را با استفاده از رشته filter انجام می دهد.

پوسته

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
}
EOM

مرجع providers.vehicles.list را ببینید.

جاوا

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
    .setParent(parent)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  ListVehiclesResponse listVehiclesResponse =
      vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

سفرها و چرخه زندگی آنها

Trip API و lifecycle مشابه Vehicle API و lifecycle است. ارائه دهنده Rideshare مسئول ایجاد سفرها با استفاده از رابط های Fleet Engine است. Fleet Engine هر دو سرویس RPC، TripService ، و منابع REST، provider.trips را ارائه می دهد. این رابط‌ها ایجاد Trip entity، درخواست‌های اطلاعات، قابلیت جستجو و قابلیت به‌روزرسانی را فعال می‌کنند.

یک Trip دارای یک فیلد وضعیت برای ردیابی پیشرفت آن در طول چرخه حیات است. مقادیر از NEW به COMPLETE به اضافه CANCELED و UNKNOWN_TRIP_STATUS منتقل می شوند. به trip_status برای RPC یا TripStatus برای REST مراجعه کنید.

  • NEW
  • ENROUTE_TO_PICKUP
  • ARRIVED_AT_PICKUP
  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • COMPLETE

سرویس شما می‌تواند سفر را از هر یک از این وضعیت‌ها به CANCELED به‌روزرسانی کند. وقتی سرویس شما یک سفر ایجاد می کند، موتور وضعیت را به عنوان NEW تنظیم می کند. vehicle_id اختیاری است. مانند وسایل نقلیه، سرویس‌ها پس از هفت روز بدون به‌روزرسانی، سفرها را به‌طور خودکار حذف می‌کنند. اگر سرویس شما سعی کند سفری را با شناسه ای که از قبل وجود دارد ایجاد کند، خطایی برگردانده می شود. اگر یک سفر در وضعیتی غیر از COMPLETE یا CANCELED شده باشد، "فعال" در نظر گرفته می شود. این تمایز در قسمت active_trips موجود در Vehicle entity و SearchTripsRequest مهم است.

این سرویس تنها زمانی می‌تواند vehicle_id اختصاص داده شده به یک سفر را تغییر دهد که وضعیت NEW یا CANCELED باشد. اگر راننده در حین مسیر سفری را لغو کند، وضعیت سفر باید قبل از تغییر یا پاک شدن vehicle_id روی NEW یا CANCELED تنظیم شود.

وضعیت هنگام اجرای پشتیبانی از سفر پشت سر هم مهم است. این پشتیبانی ارائه‌دهنده را قادر می‌سازد تا زمانی که آن وسیله نقلیه در سفر فعال است، سفر جدیدی را به یک وسیله نقلیه اختصاص دهد. کد ایجاد یک سفر پشت سر هم مانند یک سفر است و از همان شناسه وسیله نقلیه استفاده می کند. Fleet Engine مبدا و مقصد سفر جدید را به نقاط بین راهی خودرو اضافه می کند. برای اطلاعات بیشتر درباره سفرهای پشت سر هم، به ایجاد سفرهای چندراهی مراجعه کنید.

ایستگاه های بین راهی باقی مانده سفر

موجودیت Trip حاوی یک فیلد مکرر از TripWaypoint ( RPC | REST ) ​​است که به آن remainingWaypoints ( RPC | REST ) ​​می‌گویند. این فیلد شامل تمام نقاط بین راهی است که وسیله نقلیه باید به ترتیب قبل از خروج نهایی این سفر طی کند. از ایستگاه های باقی مانده وسیله نقلیه محاسبه می کند. در موارد استفاده Back-to-Back و Carpool، این لیست حاوی نقاط بین سفرهای دیگری است که قبل از این سفر از آنها عبور می شود، اما هر نقطه بین راهی بعد از این سفر را استثنا نمی کند. نقطه راه در لیست را می توان با TripId و WaypointType آن شناسایی کرد.

رابطه بین وضعیت سفر و ایستگاه های بین راهی باقی مانده وسیله نقلیه

زمانی که Fleet Engine درخواست تغییر وضعیت سفر را دریافت کرد ، نقاط بین راهی خودرو ( RPC | REST ) ​​به‌روزرسانی می‌شوند. هنگامی که tripStatus ( RPC | REST ) ​​از وضعیت دیگر به ENROUTE_TO_XXX تغییر یابد، نقطه بین راه قبلی از لیست نقاط باقیمانده خودرو حذف خواهد شد. یعنی زمانی که وضعیت سفر از ENROUTE_TO_PICKUP به ARRIVED_AT_PICKUP تغییر می‌کند، نقطه تحویل سفر همچنان در لیست ایستگاه‌های باقی‌مانده خودرو خواهد بود، اما وقتی وضعیت سفر به ENROUTE_TO_INTERMEDIATE_DESTINATION یا ENROUTE_TO_DROPOFF تغییر می‌کند، پس از آن، نقطه تحویل از وسیله نقلیه حذف می‌شود.

این برای ARRIVED_AT_INTERMEDIATE_DESTINATION و ENROUTE_TO_INTERMDEDIATE_DESTINATION یکسان است. هنگامی که ARRIVED_AT_INTERMEDIATE_DESTINATION، مقصد میانی کنونی از لیست ایستگاه های بین راهی خودرو حذف نمی شود تا زمانی که خودرو گزارش دهد که به سمت ایستگاه بین راهی بعدی می رود.

وقتی وضعیت سفر به COMPLETED تغییر می‌کند، هیچ نقطه‌ای از این سفر در فهرست ایستگاه‌های باقی‌مانده خودرو نخواهد بود.

نحوه انجام: یک سفر ایجاد کنید

یک نهاد Trip باید ایجاد شود تا هر درخواست سفر ردیابی شود و با وسایل نقلیه موجود در ناوگان مطابقت داده شود. از نقطه پایانی CreateTrip با CreateTripRequest برای ایجاد یک سفر استفاده کنید.

ویژگی های زیر برای ایجاد یک سفر مورد نیاز است:

  • parent - رشته ای که شامل شناسه ارائه دهنده است که هنگام ایجاد پروژه Google Cloud ایجاد شده است.
  • trip_id - رشته ای که توسط ارائه دهنده Rideshare ایجاد شده است.
  • trip - کانتینری با ابرداده اصلی که سفر را توصیف می کند.
    • trip_type - تعداد نشان دهنده این است که آیا این سفر ممکن است سواران دیگری از مبدأ و مقصد متفاوت در یک وسیله نقلیه ( SHARED ) یا تنها یک طرف ( EXCLUSIVE ) داشته باشد.
    • pickup_point - TerminalLocation نشان دهنده نقطه مبدا برای سفر. به مرجع RPC یا مرجع REST مراجعه کنید

هنگام ایجاد سفر، می‌توانید number_of_passengers ، dropoff_point و vehicle_id را ارائه دهید. اگرچه این فیلدها الزامی نیستند، اما اگر آنها را ارائه کنید، حفظ می شوند. همه فیلدهای سفر دیگر نادیده گرفته می شوند. به عنوان مثال، همه سفرها با یک trip_status NEW شروع می‌شوند، حتی اگر در درخواست ایجاد یک trip_status CANCELED عبور کنید.

مثال

مثال زیر سفری به مرکز خرید بزرگ اندونزی شرقی ایجاد می کند. این سفر دو نفره و اختصاصی است. provider_id Trip باید با شناسه پروژه یکی باشد. در مثال، ارائه‌دهنده Rideshare پروژه Google Cloud، project-id ایجاد کرد. این پروژه باید دارای حساب های سرویس مورد استفاده برای فراخوانی Fleet Engine باشد. وضعیت سفر NEW است.

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

پوسته

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "tripType": "EXCLUSIVE",
  "numberOfPassengers": 2,
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  }
}
EOM

مرجع providers.trips.create را ببینید.

جاوا

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
    .setPickupPoint(                 // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    // Provide the number of passengers if available.
    .setNumberOfPassengers(2)
    // Provide the drop-off point if available.
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
    .build();

CreateTripRequest createTripRequest =
    CreateTripRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setTripId("tid-1f97")  // Trip ID assigned by the Provider
        .setTrip(trip)              // Initial state
        .build();

// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.

try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

گزارش‌های پلتفرم Google Cloud برای Trip Creation

هنگامی که تماسی با نقطه پایانی CreateTrip دریافت می‌شود، Fleet Engine API یک ورودی گزارش را با استفاده از گزارش‌های پلتفرم Google Cloud می‌نویسد. ورودی گزارش شامل اطلاعاتی در مورد مقادیر در درخواست CreateTrip است. در صورت موفقیت آمیز بودن تماس، اطلاعات مربوط به Trip که برگردانده شده است نیز خواهد بود.

نحوه انجام: یک سفر را به روز کنید

موجودیت سفر حاوی فیلدهایی است که امکان ردیابی توسط سرویس و گزارش پیشرفت سفر توسط Driver SDK و Consumer SDK را فراهم می کند. برای به روز رسانی ویژگی ها، از پیام UpdateTripRequest استفاده کنید. این فیلدهای Trip را مطابق با field_mask درخواست به روز می کند. به UpdateTripRequest مراجعه کنید.

ارائه دهنده Rideshare مسئول به روز رسانی ویژگی های زیر است:

  • وضعیت سفر
  • شناسه خودرو چه در زمان ایجاد، یا پس از تطبیق وسیله نقلیه با یک سفر.
  • تغییرات در مسیرهای تحویل، خروج یا ایستگاه های بین راه.

هنگام استفاده از ویژگی Journey Sharing از طریق Driver SDK یا Consumer SDK، Fleet Engine به طور خودکار فیلدهای زیر را به روز می کند:

  • مسیرها
  • ETA
  • فاصله باقی مانده
  • مکان وسیله نقلیه
  • نقاط بین راه

به Trip in RPC یا Resource.Trip in REST مراجعه کنید.

گزارش‌های پلتفرم Google Cloud برای به‌روزرسانی‌های سفر

هنگامی که تماسی با نقطه پایانی UpdateTrip دریافت می شود، Fleet Engine API یک ورودی گزارش را با استفاده از گزارش های پلت فرم Google Cloud می نویسد. ورودی گزارش شامل اطلاعاتی در مورد مقادیر در درخواست UpdateTrip است. در صورت موفقیت آمیز بودن تماس، اطلاعات مربوط به Trip که برگردانده شده است نیز خواهد بود.

نحوه انجام: جستجوی سفرها

Fleet Engine از جستجوی سفرها پشتیبانی می کند. همانطور که قبلا ذکر شد، یک سفر به طور خودکار پس از هفت روز حذف می شود، بنابراین SearchTrips تاریخچه کامل همه سفرها را نشان نمی دهد.

در حالی که SearchTrips یک API انعطاف پذیر است، لیست زیر دو مورد استفاده را در نظر می گیرد.

  • تعیین سفرهای فعال وسیله نقلیه - ارائه دهنده می تواند سفرهای فعال فعلی یک وسیله نقلیه را تعیین کند. در SearchTripsRequest ، vehicle_id روی خودروی مورد بررسی تنظیم می شود و active_trips_only باید روی true تنظیم شود.

  • تطبیق وضعیت ارائه دهنده و موتور ناوگان -- ارائه دهنده می تواند از SearchTrips برای اطمینان از مطابقت وضعیت سفر خود و موتور ناوگان استفاده کند. این به ویژه برای TripStatus مهم است. اگر وضعیت یک سفر اختصاص داده شده به یک وسیله نقلیه به درستی روی COMPLETE یا CANCELED تنظیم نشده باشد، وسیله نقلیه توسط SearchVehicles لحاظ نمی شود.

برای استفاده از SearchTrips در این روش، vehicle_id خالی بگذارید، active_trips_only روی true تنظیم کنید، و minimum_staleness را روی زمانی بیشتر از مدت زمان سفر تنظیم کنید. به عنوان مثال، شما ممکن است یک ساعت استفاده کنید. نتایج شامل سفرهایی می‌شود که کامل یا لغو نشده‌اند و در مدت بیش از یک ساعت به‌روزرسانی نشده‌اند. ارائه دهنده باید این سفرها را بررسی کند تا مطمئن شود که وضعیت آنها در موتور ناوگان به درستی به روز شده است.

عیب یابی

در مورد خطای DEADLINE_EXCEEDED ، وضعیت موتور ناوگان ناشناخته است. ارائه‌دهنده باید دوباره CreateTrip فراخوانی کند که یا 201 (CREATED) یا 409 (CONFLICT) را برمی‌گرداند. در مورد دوم، درخواست قبلی قبل از DEADLINE_EXCEEDED با موفقیت انجام شد. برای اطلاعات بیشتر در مورد رسیدگی به خطاهای سفر: Android یا iOS به راهنمای مصرف‌کننده API مراجعه کنید.

پشتیبانی از سواری کارپول

می توانید چندین سفر SHARED را به وسیله نقلیه ای اختصاص دهید که از TripType.SHARED پشتیبانی می کند. هنگام اختصاص دادن vehicle_id برای یک سفر مشترک (در یک درخواست CreateTrip یا UpdateTrip ) باید ترتیب تمام نقاط بین راه را برای همه سفرهای اختصاص داده شده به وسیله نقلیه در این سفر مشترک از طریق Trip.vehicle_waypoints مشخص کنید. برای RPC به vehicle_waypoints برای RPC یا vehicleWaypoints برای REST مراجعه کنید.

پشتیبانی از چندین مقصد

مقصد میانی را مشخص کنید

فیلد intermediateDestinations و فیلد intermediateDestinationIndex در Trip ( RPC | REST ) ​​برای نشان دادن مقصد ترکیب شده‌اند.

مقصد میانی را به‌روزرسانی کنید

می توانید مقصدهای میانی را از طریق UpdateTrip به روز کنید. هنگام به‌روزرسانی مقصدهای میانی، باید فهرست کاملی از مقاصد میانی، از جمله مقصدهایی که بازدید شده‌اند، ارائه کنید، نه فقط مقصدهایی که به تازگی اضافه شده یا باید اصلاح شوند. هنگامی که intermediateDestinationIndex به شاخصی بعد از موقعیت مقصد میانی تازه اضافه شده/تغییر شده اشاره می کند، مقصد میانی جدید/به روز شده به waypoints خودرو یا remainingWaypoints سفر اضافه نمی شود. دلیل آن این است که هر مقصد میانی قبل از intermediateDestinationIndex به عنوان بازدید شده قبلی در نظر گرفته می شود.

وضعیت سفر تغییر می کند

فیلد intermediateDestinationsVersion in ( RPC | REST ) ​​در درخواست به‌روزرسانی وضعیت سفر که به Fleet Engine ارسال می‌شود، لازم است تا نشان دهد مقصد میانی گذشته است. مقصد میانی مورد نظر از طریق فیلد intermediateDestinationIndex مشخص می شود. هنگامی که tripStatus ( RPC | استراحت ) Enroute_to_intermediate_destination است ، تعدادی بین [0..N-1] نشان می دهد که مقصد واسطه ای وسیله نقلیه در مرحله بعدی عبور خواهد کرد. هنگامی که tripStatus به دست آمده_ at_intermediate_destination ، یک عدد بین [0..N-1] نشان می دهد که در کدام مقصد میانی وسیله نقلیه در آن قرار دارد.

مثال

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

جاوا

static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to update.
Trip trip = Trip.newBuilder()
    // Trip status cannot go back to a previous status once it is passed
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
    // Enrouting to the first intermediate destination.
    .setIntermediateDestinationIndex(0)
    // intermediate_destinations_version MUST be provided to ensure you
    // have the same picture on intermediate destinations list as FleetEngine has.
    .setIntermediateDestinationsVersion(
        trip.getIntermediateDestinationsVersion())
    .build();

// Trip update request
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(
            FieldMask.newBuilder()
                .addPaths("trip_status")
                .addPaths("intermediate_destination_index")
                // intermediate_destinations_version must not be in the
                // update mask.
                .build())
        .build();

// Error handling
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:  // Trip does not exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid, or the
                                // intermediate_destinations_version
                                // doesn’t match FleetEngine’s.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

چگونه به: پیام های اعلان از API موتور ناوگان مشترک شوید

API موتور ناوگان از Google Cloud Pub/Sub برای انتشار اعلان ها در مورد موضوع ایجاد شده توسط پروژه Consumer Google Cloud استفاده می کند. Pub/Sub به طور پیش فرض برای موتور ناوگان در پروژه Google Cloud شما فعال نیست. لطفاً برای فعال کردن PUB/SUB با مهندس مشتری خود تماس بگیرید یا با مهندس مشتری خود تماس بگیرید.

برای ایجاد موضوعی در پروژه ابری خود ، این دستورالعمل ها را دنبال کنید. شناسه موضوع باید "fleet_engine_notifications" باشد.

موضوع باید در همان پروژه ابری ایجاد شود که API های موتور ناوگان را فراخوانی می کند.

پس از ایجاد موضوع ، شما باید به API موتور ناوگان اجازه انتشار موضوع را بدهید. برای انجام این کار ، روی موضوعی که تازه ایجاد کرده اید کلیک کرده و مجوز جدیدی اضافه کنید. ممکن است برای باز کردن ویرایشگر مجوزها روی پانل اطلاعاتی کلیک کنید. اصلی باید geo-fleet-engine@system.gserviceaccount.com باشد و نقش باید Pub/Sub publisher باشد.

به منظور راه اندازی پروژه ابری خود برای عضویت در اعلان ها ، این دستورالعمل ها را دنبال کنید

API موتور ناوگان هر اعلان را در دو قالب داده مختلف ، protobuf و json منتشر می کند. قالب داده برای هر اعلان در ویژگی های pubsubmessage با کلید به عنوان data_format و مقدار به عنوان protobuf یا json مشخص شده است.

طرح اعلان:

پروتوبوف

// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
  // Required. At least one notification must exist.
  // List of notifications containing information related to changes in
  // Fleet Engine data.
  repeated Notification notifications = 1;
}

// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
  // Required. At least one type must exist.
  // Type of notification.
  oneof type {
    // Notification related to changes in vehicle data.
    VehicleNotification vehicle_notification = 1;
  }
}

// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
  // Required.
  // Vehicle must contain all fields that were set when it was created.
  Vehicle vehicle = 1;
}

// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
  // Required.
  // Vehicle must only contain name and fields that are present in the
  // field_mask field below.
  Vehicle vehicle = 1;

  // Required.
  // Contains vehicle field paths that were specifically requested
  // by the Provider.
  google.protobuf.FieldMask field_mask = 2;
}

// Notification related to changes in vehicle data.
message VehicleNotification {
  // Required. At least one type must be set.
  // Type of notification.
  oneof type {
    // Notification sent when a new vehicle was created.
    CreateVehicleNotification create_notification = 1;
    // Notification sent when an existing vehicle is updated.
    UpdateVehicleNotification update_notification = 2;
  }
}

JSON

BatchNotification: {
  "description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
  "type": "object",
  "required": ["notifications"],
  "properties": {
    "notifications": {
      "description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
      "type": "Notification[]"
    }
  }
}

Notification: {
  "description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
  "type": "object",
  "properties": {
    "vehicleNotification": {
      "description": "Notification related to changes in vehicle data.",
      "type": "VehicleNotification"
    }
  }
}

VehicleNotification: {
  "description": "Notification related to changes in vehicle data.",
  "type": "object",
  "properties": {
    "createNotification": {
      "description": "Notification sent when a new vehicle was created.",
      "type": "CreateVehicleNotification"
    },
    "updateNotification": {
      "description": "Notification sent when an existing vehicle is updated.",
      "type": "UpdateVehicleNotification"
    }
  }
}

CreateVehicleNotification: {
  "description": "Notification sent when a new vehicle was created.",
  "type": "object",
  "required": ["vehicle"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must contain all fields that were set when it was created.",
      "type": "Vehicle"
    }
  }
}

UpdateVehicleNotification: {
  "description": "Notification sent when an existing vehicle is updated.",
  "type": "object",
  "required": ["vehicle", "fieldMask"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
      "type": "Vehicle"
    },
    "fieldMask": {
      "description": "Contains vehicle field paths that were specifically requested by the Provider.",
      "type": "FieldMask"
    }
  }
}