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

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

پیش نیازها

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

توجه: استفاده از محیط تعاملی Cloud Shell را در نظر بگیرید که در آن Cloud SDK و سایر وابستگی‌ها مانند curl قبلاً نصب شده‌اند. استفاده از Cloud Shell را ببینید.

پوسته

gcloud auth login

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

You are now logged in as [[e-mail]].
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:[e-mail] \
       --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:[e-mail] \
       --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:[e-mail] \
       --role=roles/fleetengine.serviceSuperUser

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

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

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

gcloud projects add-iam-policy-binding project-id \
       --member=user:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

جایی که [e-mail] ایمیلی است که برای احراز هویت با gcloud استفاده می‌شود ( gcloud auth list --format='value(account)' ).

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

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

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

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

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

مهم: ما به شدت توصیه می کنیم از کتابخانه تأیید Fleet Engine با همه پیاده سازی های جاوا استفاده کنید.

ایجاد یک توکن وب 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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "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:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

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

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

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

gcloud beta iam service-accounts sign-jwt --iam-account=[e-mail] 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 برای ایجاد یک وسیله نقلیه استفاده کنید.

توجه: CreateVehicle به یک حساب کاربری با نقش Fleet Engine Super User نیاز دارد.

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 برای ماسک های میدان است.

توجه: قسمت update_mask باید همیشه تنظیم شود. تنظیم نکردن فیلد update_mask پیش‌فرض برای نوشتن همه فیلدها است. این می تواند منجر به رفتار ناخواسته شود.

همانطور که در 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 عمل می کند.

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

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

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 مبدا و مقصد سفر جدید را به نقاط بین راهی خودرو اضافه می کند. برای اطلاعات بیشتر درباره سفرهای پشت سر هم، به ایجاد سفرهای چندراهی مراجعه کنید.

توجه: موتور ناوگان از حذف صریح سفر پشتیبانی نمی کند. این سرویس به طور خودکار سفرها را پس از هفت روز بدون به روز رسانی حذف می کند. Google داده های شخصی را حفظ نمی کند. اگر می‌خواهید داده‌های سفر را حفظ کنید، ارائه‌دهنده Rideshare باید آن عملکرد را پیاده‌سازی کند.

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

موجودیت 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 عبور کنید.

توجه: استفاده از CreateTrip به اعتبارنامه حساب ممتاز ذکر شده در راه‌اندازی پروژه Cloud نیاز دارد.

مثال

مثال زیر سفری به مرکز خرید بزرگ اندونزی شرقی ایجاد می کند. این سفر دو نفره و اختصاصی است. 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 مراجعه کنید.

توجه: استفاده از UpdateTripRequest برای به روز رسانی trip_status یا vehicle_id سفر به اعتبار حساب ممتاز ارائه دهنده نیاز دارد.

ارائه دهنده 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 مراجعه کنید.

توجه: Trip.vehicle_waypoints باید شامل تمام نقاط بین راهی باقیمانده از تمام سفرهایی باشد که به وسیله نقلیه اختصاص داده شده است، اما نقاط بین راه اضافی نداشته باشند. این ایستگاه‌های بین راهی باید به‌گونه‌ای ترتیب داده شوند که برای یک سفر معین، نقطه تحویل قبل از مقاصد میانی و همه مقصدهای میانی قبل از نقطه سقوط قرار گیرند. ایستگاه های بین راهی سفر EXCLUSIVE نباید با هیچ سفر دیگری تداخل داشته باشد.

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

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

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

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

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

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

فیلد intermediateDestinationsVersion in ( RPC | REST ) ​​در درخواست به‌روزرسانی وضعیت سفر که به Fleet Engine ارسال می‌شود، لازم است تا نشان دهد مقصد میانی گذشته است. مقصد میانی مورد نظر از طریق فیلد intermediateDestinationIndex مشخص می شود. وقتی tripStatus ( RPC | REST ) ENROUTE_TO_INTERMEDIATE_DESTINATION است، عددی بین [0..N-1] نشان می دهد که وسیله نقلیه از کدام مقصد میانی بعدی عبور خواهد کرد. وقتی tripStatus ARRIVED_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 با مهندس مشتری خود تماس بگیرید یا با مهندس مشتری خود تماس بگیرید.

توجه: Pub/Sub سفارش پیام ها را تضمین نمی کند.

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

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

پس از ایجاد موضوع ، شما باید به API موتور ناوگان اجازه انتشار موضوع را بدهید. برای انجام این کار ، روی موضوعی که تازه ایجاد کرده اید کلیک کرده و مجوز جدیدی اضافه کنید. ممکن است برای باز کردن ویرایشگر مجوزها روی پانل اطلاعاتی کلیک کنید. اصلی باید [e-mail] باشد و نقش باید 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"
    }
  }
}

،

موتور ناوگان در صورت تقاضا و تحویل API به شما امکان می دهد سفرها و وضعیت وسیله نقلیه را برای سفر خود مدیریت کنید و برنامه های پیشرفت را سفارش دهید. این معاملات بین Driver SDK ، Consumer SDK و سرویس پس زمینه شما را انجام می دهد - که می تواند با برقراری تماس GRPC یا استراحت با موتور ناوگان ارتباط برقرار کند.

پیش نیازها

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

توجه: استفاده از محیط تعاملی Cloud Shell را در نظر بگیرید که Cloud SDK و سایر وابستگی های دیگر مانند curl از قبل نصب شده اند. با استفاده از پوسته ابر مشاهده کنید.

پوسته

gcloud auth login

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

You are now logged in as [[e-mail]].
Your current project is [project-id].  You ...

توجه: مقادیر متغیر را در بلوک های کد ویرایش کنید تا دستورات بعدی را تهیه کنید تا بتوانند مستقیماً کپی و چسبانده شوند.

بررسی کنید که API های موتور ناوگان راه حل در صورت تقاضا و تحویل ، به طور مناسب پیکربندی شده اند.

پوسته

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

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

ورود به سیستم

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

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

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

ما کتابخانه های مشتری را در چندین زبان برنامه نویسی مشترک منتشر می کنیم. این کتابخانه ها به ارائه تجربه بهتر توسعه دهنده نسبت به استراحت خام یا GRPC کمک می کنند. برای راهنمایی در مورد نحوه به دست آوردن کتابخانه های مشتری برای برنامه سرور خود ، به کتابخانه های مشتری مراجعه کنید.

نمونه های جاوا در این مستندات ، آشنایی با GRPC را فرض می کنند.

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

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

تنظیم پروژه ابری

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

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

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

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

سفر و پیشرفت سفارش از نقش های زیر استفاده می کند:

نقش	شرح
کاربر 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:[e-mail] \
       --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:[e-mail] \
       --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:[e-mail] \
       --role=roles/fleetengine.serviceSuperUser

SDK های راننده و مصرف کننده در اطراف این نقش های استاندارد ساخته شده اند.

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

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

gcloud projects add-iam-policy-binding project-id \
       --member=user:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

جایی که [e-mail] ایمیلی است که برای تأیید اعتبار با GCLOUD ( gcloud auth list --format='value(account)' استفاده می شود).

توجه: این اجازه می دهد تا از هرگونه حساب خدمات در پروژه ، جعل هویت را جعل کند. برای تنظیم مجوزهای ریز دانه تر ، مستندات IAM را در مورد اتصال نقش های Scoping به یک حساب خدمات خاص دنبال کنید.

ناوگان موتور کتابخانه AUT

Fleet Engine از نشانه های وب JSON (JWTS) برای محدود کردن دسترسی به API های موتور ناوگان استفاده می کند. کتابخانه جدید موتور ناوگان ، که در GitHub موجود است ، ساخت JWT های موتور ناوگان را ساده می کند و آنها را به طور ایمن امضا می کند.

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

• روند ایجاد نشانه های موتور ناوگان را ساده می کند.
• مکانیسم های امضای توکن غیر از استفاده از پرونده های اعتبار (مانند جعل هویت یک حساب سرویس) را فراهم می کند.
• نشانه های امضا شده را به درخواست های برون مرزی که از یک خرد خرد GRPC یا مشتری GAPIC ساخته شده است ، پیوست می کند.

مهم: ما به شدت توصیه می کنیم از کتابخانه Auth Engine Engine با تمام پیاده سازی های جاوا استفاده کنید.

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

هنگام استفاده از کتابخانه Auth Engine Engine ، Tokens Json Web (JWTS) باید مستقیماً در پایگاه کد شما ساخته شود. این امر شما را ملزم به درک عمیق از JWT ها و نحوه ارتباط آنها با موتور ناوگان می کند. به همین دلیل ما از کتابخانه Auth Engine Auth استفاده می کنیم.

در داخل موتور ناوگان ، توکن های وب JSON (JWTS) احراز هویت کوتاه مدت را ارائه می دهند و اطمینان می دهند که دستگاه ها فقط می توانند وسایل نقلیه ، سفرها یا کارهایی را که مجاز به آنها هستند اصلاح کنند. JWT ها حاوی یک هدر و یک بخش ادعا هستند. بخش هدر شامل اطلاعاتی مانند کلید خصوصی برای استفاده (به دست آمده از حساب های سرویس) و الگوریتم رمزگذاری است. بخش ادعای شامل اطلاعاتی مانند Token's Create Time Time ، Tokens Time برای زندگی ، خدماتی است که ادعا می کند به آن دسترسی دارد و سایر اطلاعات مجوز برای دسترسی به دسترسی. به عنوان مثال ، شناسه وسیله نقلیه.

بخش هدر 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 دقیقه اجازه دهید. اگر Timestamp در گذشته یا در آینده خیلی دور باشد ، سرور ممکن است خطایی را گزارش کند.
انقضا	زمانی که توکن منقضی می شود ، مشخص شده در ثانیه ها از ساعت 00:00:00 UTC ، 1 ژانویه 1970 سپری شده است. در صورتی که زمان بندی بیش از یک ساعت در آینده باشد ، این درخواست از بین می رود.
مجوز	بسته به مورد استفاده ، ممکن است حاوی "وسیله نقلیه" یا "Tripid" باشد.

ایجاد یک نشانه JWT به امضای آن اشاره دارد. برای راهنمایی و نمونه کد برای ایجاد و امضای JWT ، به مجوز حساب خدمات بدون OAuth مراجعه کنید. سپس می توانید یک نشانه امضا شده را به تماس های GRPC یا سایر روشهای استفاده شده برای دسترسی به موتور ناوگان وصل کنید.

ادعاهای JWT

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

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

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

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

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

موارد زیر نمونه ای از سرور ارائه دهنده را نشان می دهد:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_provider_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "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": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

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

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

• برای kid Field در عنوان ، شناسه کلید خصوصی حساب خدمات خود را مشخص کنید. شما می توانید این مقدار را در قسمت private_key_id پرونده JSON حساب خدمات خود پیدا کنید.
• برای iss و sub Fields ، آدرس ایمیل حساب خدمات خود را مشخص کنید. می توانید این مقدار را در قسمت client_email پرونده json حساب سرویس خود پیدا کنید.
• برای قسمت aud ، https: // service_name/ را مشخص کنید.
• برای قسمت iat ، هنگام ایجاد توکن ، از Timestamp استفاده کنید ، به عنوان ثانیه های سپری شده از ساعت 00:00:00 UTC ، 1 ژانویه 1970 مشخص شده است. 10 دقیقه اجازه دهید. اگر Timestamp در گذشته یا در آینده خیلی دور باشد ، سرور ممکن است خطایی را گزارش کند.
• برای قسمت exp ، از زمان استفاده از Timestamp استفاده کنید ، از زمان 00:00:00 UTC ، 1 ژانویه 1970 ، ثانیه مشخص شده است. حداکثر مقدار مجاز iat + 3600 است.

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

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

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

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

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

gcloud projects add-iam-policy-binding project-id \
       --member=user:[e-mail] \
       --role=roles/iam.serviceAccountTokenCreator

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

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

سپس دستور gcloud زیر را اجرا کنید تا نشانه را به نمایندگی از حساب خدمات فوق العاده کاربری خود امضا کنید:

gcloud beta iam service-accounts sign-jwt --iam-account=[e-mail] unsigned_token.json signed_token.jwt

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

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

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

وسایل نقلیه و چرخه عمر آنها

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

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

به روزرسانی موقعیت مکانی وسیله نقلیه

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

1. از درایور 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 رفتار می شود.

ویژگی های وسیله نقلیه

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

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

وسیله نقلیه باقی مانده وسیله نقلیه

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

گسترش صلاحیت یک وسیله نقلیه برای مسابقات

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

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

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

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

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

توجه: CreateVehicle به یک حساب کاربری فوق العاده موتور ناوگان نیاز به یک حساب کاربری دارد.

provider_id Vehicle باید شناسه پروژه (به عنوان مثال پروژه My-on-Demand) پروژه Google Cloud باشد که حاوی حسابهای خدماتی است که برای تماس با موتور ناوگان استفاده می شود. توجه داشته باشید که در حالی که حساب های خدمات متعدد ممکن است برای همان ارائه دهنده تحویل یا ارائه دهنده تحویل به موتور ناوگان دسترسی پیدا کنند ، موتور ناوگان در حال حاضر از حساب های خدمات از چندین پروژه 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

به Providers.vehicles.Create Reference مراجعه کنید.

جاوا

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 Platform برای ایجاد وسیله نقلیه

API موتور ناوگان هنگام دریافت تماس به نقطه پایانی CreateVehicle ، ورود به سیستم را از طریق Google Cloud Platform می نویسد. ورود به سیستم شامل اطلاعاتی در مورد مقادیر موجود در درخواست 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'

Pub Cloud/اعلان های زیر برای ایجاد وسیله نقلیه

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

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

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

مثال

پوسته

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

به ارائه دهندگان. 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 نیاز به امتیازات فوق العاده کاربر ناوگان دارد.

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

توجه: قسمت update_mask همیشه باید تنظیم شود. تنظیم پیش فرض های زمینه update_mask برای نوشتن همه زمینه ها. این می تواند منجر به رفتار ناخواسته شود.

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

مثال

این مثال 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

به ارائه دهندگان. 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 Platform برای به روزرسانی وسایل نقلیه

API موتور ناوگان هنگام دریافت تماس به نقطه پایانی UpdateVehicle ورود به سیستم ورود به سیستم را از طریق Google Cloud Platform می نویسد. ورود به سیستم شامل اطلاعات مربوط به مقادیر موجود در درخواست 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/اعلان های فرعی برای به روزرسانی وسایل نقلیه

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

چگونه به: وسایل نقلیه جستجو

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

مثال

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

پوسته

ابتدا مکان وسیله نقلیه را که در مراحل قبلی ایجاد کرده ایم به روز کنید تا واجد شرایط باشد. در دنیای واقعی ، این کار توسط درایور SDK که روی دستگاه Android یا 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

به ارائه دهندگان. 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 عمل می کند.

توجه: استفاده از فیلد پرس و filter از فیلتر مورد نیاز ، required_attributes ، required_one_of_attributes و زمینه های required_one_of_attributes_sets ، بسیار توصیه می شود ، زیرا filter برای جایگزینی این زمینه ها طراحی شده است. اگر یک مقدار غیر خالی در قسمت filter مشخص شده باشد ، قسمتهای زیر باید خالی باشند: required_attributes ، required_one_of_attributes ، و required_one_of_attributes_sets .

چگونه به: لیست وسایل نقلیه

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

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

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

مثال

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

پوسته

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 Reference مراجعه کنید.

جاوا

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;
}

سفرها و چرخه عمر آنها

API سفر و چرخه عمر مشابه API وسیله نقلیه و چرخه عمر است. ارائه دهنده Rideshare وظیفه ایجاد سفر با استفاده از رابط های موتور ناوگان را بر عهده دارد. موتور ناوگان هم سرویس RPC ، TripService و منابع REST را ارائه می دهد ، provider.trips . این رابط ها امکان ایجاد Entity Trip ، درخواست های اطلاعاتی ، عملکرد جستجو و قابلیت به روزرسانی را فراهم می کنند.

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

• 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 در موجودیت خودرو و SearchTripsRequest مهم است.

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

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

توجه: موتور ناوگان از حذف صریح سفر پشتیبانی نمی کند. این سرویس به طور خودکار سفرها را بعد از هفت روز بدون به روزرسانی حذف می کند. Google داده های شخصی را حفظ نمی کند. اگر می خواهید داده های سفر را حفظ کنید ، ارائه دهنده RESESHARE باید این عملکرد را پیاده سازی کند.

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

نهاد سفر حاوی یک زمینه مکرر از TripWaypoint ( RPC | استراحت ) است که به نام remainingWaypoints ( RPC | REST ) ​​نامیده می شود. این قسمت شامل تمام نقاط راه است که وسیله نقلیه قبل از نهایی شدن این سفر به ترتیب نیاز به سفر دارد. این محاسبه از ایستگاه های باقی مانده وسیله نقلیه است . در موارد پشتی و استفاده از کارپول ، این لیست شامل نقاط راه از سفرهای دیگر است که قبل از این سفر طی می شود ، اما هر نقطه راه را بعد از این سفر حذف نمی کند. نقطه راه در لیست را می توان با TripId و WaypointType آن شناسایی کرد.

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

ایستگاه های راه باقی مانده وسیله نقلیه ( RPC | استراحت ) هنگامی که موتور ناوگان درخواست تغییر وضعیت سفر را دریافت می کند ، به روز می شود. وقتی tripStatus ( RPC | REST ) ​​از وضعیت دیگر به Enroute_to_xxx تغییر می یابد ، از لیست Waypoints باقی مانده وسیله نقلیه حذف می شود. یعنی هنگامی که وضعیت سفر از Enroute_to_pickup به rocoy_at_pickup تغییر می یابد ، نقطه وانت سفر همچنان در لیست ایستگاه های راه باقی مانده خودرو قرار خواهد گرفت ، اما وقتی وضعیت سفر به eneroute_to_intermediate_destination یا eneroute_to_dropoff تغییر می یابد ، وانت آن سپس از نقطه راه راه باقی مانده خودرو خارج می شود.

این همان برای reption_at_intermediate_destination و enroute_to_intermdediate_destination است. هنگامی که وارد شده_ at_intermediate_destination ، مقصد واسطه فعلی از لیست ایستگاه های جاده ای باقی مانده وسیله نقلیه حذف نمی شود تا زمانی که خودرو گزارش دهد که آن را به نقطه راه بعدی می رساند.

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

چگونه به: سفر ایجاد کنید

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

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

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

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

توجه: استفاده از CreateTrip برای حساب ممتاز ذکر شده در تنظیم پروژه Cloud ، به اعتبارنامه نیاز دارد.

مثال

مثال زیر سفری به بازار گراند اندونزی شرقی ایجاد می کند. این سفر برای دو مسافر است و منحصر به فرد است. provider_id Trip باید همانند شناسه پروژه باشد. به عنوان مثال ، ارائه دهنده REDESHARE پروژه Google Cloud ، project-id ایجاد کرد. این پروژه باید حسابهای خدماتی را که برای تماس با موتور ناوگان استفاده می شود ، داشته باشد. وضعیت سفر 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 Reference مراجعه کنید.

جاوا

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 Platform برای ایجاد سفر ثبت نام می کند

API موتور ناوگان هنگام دریافت تماس با Google Cloud Platform در هنگام دریافت تماس با CreateTrip Cloud Platform ، ورود به سیستم را می نویسد. ورود به سیستم شامل اطلاعاتی در مورد مقادیر موجود در درخواست CreateTrip است. اگر این تماس موفق شود ، اطلاعات مربوط به Trip بازگشت را نیز شامل می شود.

چگونه به: سفر را به روز کنید

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

توجه: استفاده از UpdateTripRequest برای به روزرسانی سفر trip_status یا vehicle_id نیاز به اعتبارنامه برای حساب ممتاز ارائه دهنده دارد.

ارائه دهنده Rideshare وظیفه به روزرسانی ویژگی های زیر را بر عهده دارد:

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

موتور ناوگان هنگام استفاده از ویژگی اشتراک سفر از طریق درایور SDK یا SDK مصرف کننده ، به طور خودکار زمینه های زیر را به روز می کند:

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

به Trip در RPC یا Resource.Trip در استراحت مراجعه کنید.

Google Cloud Platform برای به روزرسانی های سفر ثبت نام می کند

API موتور ناوگان هنگام دریافت تماس به نقطه انتهایی UpdateTrip ، ورود به سیستم را با استفاده از Google Cloud Platform می نویسد. ورود به سیستم شامل اطلاعات مربوط به مقادیر موجود در درخواست UpdateTrip است. اگر این تماس موفق شود ، اطلاعات مربوط به Trip بازگشت را نیز شامل می شود.

چگونه به: سفرهای جستجو

موتور ناوگان از جستجوی سفرها پشتیبانی می کند. همانطور که قبلاً نیز اشاره شد ، یک سفر پس از هفت روز به طور خودکار حذف می شود ، بنابراین 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 (ایجاد شده) یا 409 (درگیری) را برمی گرداند. در مورد دوم ، درخواست قبلی قبل از DEADLINE_EXCEEDED موفق شد. برای اطلاعات بیشتر در مورد رسیدگی به خطاهای سفر: Android یا iOS به راهنماهای API مصرف کننده مراجعه کنید.

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

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

توجه: Trip.vehicle_waypoints باید شامل تمام نقاط راه باقی مانده از تمام سفرهایی که به وسیله نقلیه اختصاص داده شده اند ، اما دارای نقاط راه اضافی نیستند. These waypoints must be ordered such that for a given trip, the pickup point is before intermediate destinations and all intermediate destinations are before the dropoff point. EXCLUSIVE trip's waypoints must not interleave with any other trips.

Multiple destinations support

Identify an intermediate destination

The field intermediateDestinations and field intermediateDestinationIndex in Trip ( RPC | REST ) are combined to be used to indicate the destination.

Update intermediate destination

You can update the intermediate destinations via UpdateTrip . When updating intermediate destinations, you must provide a complete list of intermediate destinations, including those that have been visited, not just the one newly added or to-be-modified. When the intermediateDestinationIndex points to an index after the position of newly added/modified intermediate destination, the new/updated intermediate destination will not be added to Vehicle's waypoints or Trip's remainingWaypoints . The reason is that any intermediate destinations before intermediateDestinationIndex are treated as already visited.

Trip status changes

The field intermediateDestinationsVersion in ( RPC | REST ) is required in the Trip status update request sent to Fleet Engine to indicate an intermediate destination has passed. The targeted intermediate destination is specified via the field intermediateDestinationIndex . When tripStatus ( RPC | REST ) is ENROUTE_TO_INTERMEDIATE_DESTINATION, a number between [0..N-1] indicates which intermediate destination the vehicle will cross next. When tripStatus is ARRIVED_AT_INTERMEDIATE_DESTINATION, a number between [0..N-1] indicates which intermediate destination the vehicle is at.

مثال

The following code example demonstrates how to update a trip's status to enroute to its first intermediate destination, assuming that you have created a multi-destination trip and the trip has passed its pickup point.

جاوا

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;
}

HOW-TO: Subscribe to notification messages from the Fleet Engine API

The Fleet Engine API uses Google Cloud Pub/Sub to publish notifications on the topic created by the consumer Google Cloud Project. Pub/Sub is not enabled by default for Fleet Engine on your Google Cloud project. Please file a support case or contact your Customer Engineer to enable Pub/Sub.

Note: Pub/Sub does not guarantee the ordering of messages.

In order to create a topic on your Cloud Project, follow these instructions. The topic ID must be 'fleet_engine_notifications'.

The topic must be created in the same Cloud project that is calling Fleet Engine APIs.

Once the topic is created, you will need to grant the Fleet Engine API permission to publish on the topic. In order to do so, click on the topic you just created and add a new permission. You might have to click on SHOW INFO PANEL to open the permissions editor. The principal should be [e-mail] and the role should be Pub/Sub publisher .

In order to setup your Cloud Project to subscribe to notifications, follow these instructions

The Fleet Engine API will publish each notification in two different data formats, protobuf and json . The data format for each notification is denoted in the PubsubMessage attributes with the key as data_format and value as protobuf or json .

Notification schema:

پروتوبوف

// 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

• وسیله نقلیه
• FieldMask

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"
    }
  }
}