Fleet Engine On-Deman Rides and Deliveries API به شما امکان می دهد سفرها و وضعیت خودرو را برای برنامه های کاربردی سفر و پیشرفت سفارش خود مدیریت کنید. این تراکنشهای بین Driver SDK، Consumer SDK و سرویس پشتیبان شما را مدیریت میکند - که میتواند با برقراری تماسهای gRPC یا REST با Fleet Engine ارتباط برقرار کند.
پیش نیازها
برای توسعه، مطمئن شوید که Cloud SDK (gcloud) را نصب کرده اید و در پروژه خود احراز هویت شده اید.
پوسته
gcloud auth login
شما باید یک پیام موفقیت آمیز مانند:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
بررسی کنید که APIهای موتور ناوگان راهحلهای سفارشی و تحویل بهطور مناسب پیکربندی شده باشند.
پوسته
gcloud --project=project-id services enable fleetengine.googleapis.com
اگر این دستور منجر به خطا شد، برای دسترسی با سرپرست پروژه و نماینده پشتیبانی Google خود تماس بگیرید.
ورود به سیستم
Fleet Engine میتواند پیامهای گزارشی را درباره تماسهای API که دریافت میکند در گزارشهای پلتفرم Google Cloud بنویسد. برای مروری بر نحوه خواندن و تجزیه و تحلیل گزارشها، به مستندات Cloud Logging مراجعه کنید.
گزارشگیری ممکن است بهطور پیشفرض برای پروژههایی که قبل از 10 فوریه 2022 ایجاد شدهاند فعال نباشد. برای جزئیات بیشتر به اسناد گزارشگیری مراجعه کنید.
کتابخانه های مشتری
ما کتابخانه های مشتری را در چندین زبان برنامه نویسی رایج منتشر می کنیم. این کتابخانه ها به ارائه تجربه بهتر توسعه دهنده نسبت به REST خام یا gRPC کمک می کنند. برای دستورالعملهای نحوه بهدست آوردن کتابخانههای سرویس گیرنده برای برنامه سرور خود، به کتابخانههای مشتری مراجعه کنید.
مثالهای جاوا در این مستندات، آشنایی با gRPC را فرض میکنند.
احراز هویت و مجوز
میتوانید قابلیتهای ارائه شده توسط Trip and Order Progress را از طریق Google Cloud Console پیکربندی کنید. این APIها و SDKها نیاز به استفاده از نشانههای وب JSON دارند که با استفاده از حسابهای سرویس ایجاد شده از کنسول Cloud امضا شدهاند.
راه اندازی پروژه ابری
برای راه اندازی پروژه ابری خود، ابتدا پروژه خود را ایجاد کنید و سپس حساب های خدماتی ایجاد کنید.
برای ایجاد پروژه Google Cloud:
- با استفاده از Google Cloud Console یک پروژه Google Cloud ایجاد کنید.
- با استفاده از API ها و داشبورد خدمات، API Local Rides and Deliveries را فعال کنید.
حسابهای سرویس با یک یا چند نقش مرتبط هستند. آنها برای ایجاد توکن های وب JSON استفاده می شوند که بسته به نقش ها مجموعه های مختلفی از مجوزها را می دهند. به طور معمول، برای کاهش احتمال سوء استفاده، می توانید چندین حساب سرویس ایجاد کنید که هر کدام دارای حداقل مجموعه ای از نقش های مورد نیاز هستند.
Trip and Order Progress از نقش های زیر استفاده می کند:
نقش | شرح |
---|---|
کاربر SDK مصرف کننده موتور ناوگانroles/fleetengine.consumerSdkUser | اجازه جستجوی وسایل نقلیه و بازیابی اطلاعات مربوط به وسایل نقلیه و سفرها را می دهد. نشانههایی که توسط یک حساب سرویس با این نقش ایجاد میشوند، معمولاً از دستگاههای تلفن همراه برنامه مصرفکننده اشتراکگذاری یا تحویل شما استفاده میشوند. |
کاربر SDK درایور موتور ناوگانroles/fleetengine.driverSdkUser | اجازه بهروزرسانی مکانها و مسیرهای خودرو و بازیابی اطلاعات مربوط به وسایل نقلیه و سفرها را میدهد. نشانههایی که توسط یک حساب سرویس با این نقش ایجاد میشوند، معمولاً از دستگاههای تلفن همراه برنامه راننده اشتراکگذاری یا تحویل شما استفاده میشوند. |
کاربر فوق العاده خدمات موتور ناوگانroles/fleetengine.serviceSuperUser | به همه APIهای وسایل نقلیه و سفرها مجوز می دهد. توکنهایی که توسط یک حساب سرویس با این نقش ایجاد میشوند، معمولاً از سرورهای پشتیبان شما استفاده میشوند. |
به عنوان مثال، برای هر یک از سه نقش یک حساب کاربری ایجاد کنید و نقش های مربوطه را به آنها اختصاص دهید.
gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
Driver و Consumer SDK بر اساس این نقش های استاندارد ساخته شده اند.
از طرف دیگر، امکان ایجاد نقشهای سفارشی وجود دارد که اجازه میدهد مجموعهای دلخواه از مجوزها با هم جمع شوند. هر زمان که مجوز لازم وجود نداشته باشد، Driver و Consumer SDK پیامهای خطا نشان میدهند. در نتیجه، ما قویاً توصیه می کنیم از مجموعه استاندارد نقش های ارائه شده در بالا استفاده کنید و از نقش های سفارشی استفاده نکنید.
برای راحتی، اگر نیاز به ایجاد نشانههای JWT برای مشتریان غیرقابل اعتماد دارید، افزودن کاربران به نقش ایجاد کننده رمز حساب سرویس به آنها امکان میدهد با ابزارهای خط فرمان gcloud توکنهایی ایجاد کنند.
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
جایی که my-user@example.com
ایمیلی است که برای احراز هویت با gcloud استفاده میشود ( gcloud auth list --format='value(account)'
).
کتابخانه تأیید موتور ناوگان
Fleet Engine از JSON Web Tokens (JWTs) برای محدود کردن دسترسی به APIهای Fleet Engine استفاده می کند. کتابخانه جدید Fleet Engine Auth که در Github موجود است ، ساخت JWTهای Fleet Engine را ساده کرده و آنها را به صورت ایمن امضا می کند.
این کتابخانه دارای مزایای زیر است:
- فرآیند ایجاد توکن های Fleet Engine را ساده می کند.
- مکانیسمهای امضای رمز را به غیر از استفاده از فایلهای اعتبار (مانند جعل هویت یک حساب سرویس) ارائه میکند.
- توکنهای امضا شده را به درخواستهای خروجی که از یک کاربر خرد gRPC یا GAPIC ارسال شده است، پیوست میکند.
ایجاد یک توکن وب JSON (JWT) برای مجوز
وقتی از کتابخانه تأیید موتور Fleet استفاده نمیکنید، توکنهای وب JSON (JWT) باید مستقیماً در پایگاه کد شما ایجاد شوند. این امر مستلزم آن است که هم درک عمیقی از JWT ها و هم ارتباط آنها با Fleet Engine داشته باشید. به همین دلیل است که ما به شدت توصیه می کنیم از کتابخانه تأیید موتور ناوگان استفاده کنید.
در Fleet Engine، JSON Web Tokens (JWT) احراز هویت کوتاه مدت را ارائه میکند و اطمینان میدهد که دستگاهها فقط میتوانند وسایل نقلیه، سفرها یا کارهایی را که برای آنها مجاز هستند تغییر دهند. JWT ها شامل یک هدر و یک بخش ادعا هستند. بخش هدر حاوی اطلاعاتی مانند کلید خصوصی برای استفاده (به دست آمده از حساب های سرویس) و الگوریتم رمزگذاری است. بخش ادعا حاوی اطلاعاتی مانند زمان ایجاد رمز، زمان زنده ماندن نشانهها، خدماتی است که ادعای دسترسی به آنها را دارد و سایر اطلاعات مجوز برای محدود کردن دسترسی. برای مثال شناسه وسیله نقلیه
یک بخش هدر JWT شامل فیلدهای زیر است:
رشته | شرح |
---|---|
alg | الگوریتم مورد استفاده "RS256". |
تایپ کنید | نوع توکن "JWT". |
بچه | شناسه کلید خصوصی حساب سرویس شما. میتوانید این مقدار را در قسمت «private_key_id» فایل JSON حساب سرویس خود بیابید. اطمینان حاصل کنید که از یک کلید از یک حساب سرویس با سطح صحیح مجوز استفاده می کنید. |
بخش ادعاهای JWT شامل فیلدهای زیر است:
رشته | شرح |
---|---|
iss | آدرس ایمیل حساب سرویس شما. |
زیر | آدرس ایمیل حساب سرویس شما. |
aud | SERVICE_NAME حساب سرویس شما، در این مورد https://fleetengine.googleapis.com/ |
iat | مُهر زمانی که نشانه ایجاد شد، برحسب ثانیه های سپری شده از ساعت 00:00:00 UTC، 1 ژانویه 1970 مشخص شده است. برای انحراف 10 دقیقه زمان بگذارید. اگر مهر زمانی در گذشته یا در آینده خیلی دور باشد، سرور ممکن است خطا را گزارش کند. |
انقضا | مهر زمانی که نشان منقضی میشود، برحسب ثانیه مشخص شده است که از ساعت 00:00:00 UTC، 1 ژانویه 1970 سپری شده است. اگر مهر زمانی بیش از یک ساعت در آینده باشد، درخواست انجام نمیشود. |
مجوز | بسته به مورد استفاده، ممکن است حاوی «vehicleid» یا «tripid» باشد. |
ایجاد یک توکن JWT به امضای آن اشاره دارد. برای دستورالعملها و نمونههای کد برای ایجاد و امضای JWT، به مجوز حساب سرویس بدون OAuth مراجعه کنید. سپس میتوانید یک نشانه امضا شده را به تماسهای gRPC یا سایر روشهای مورد استفاده برای دسترسی به Fleet Engine متصل کنید.
ادعاهای JWT
هنگام ایجاد محموله JWT، یک ادعای اضافی در بخش مجوز با کلید vehicleid
یا tripid
تنظیم شده به ارزش شناسه وسیله نقلیه یا شناسه سفری که تماس برای آن برقرار شده است، اضافه کنید.
Driver SDK همیشه از ادعای vehicleid
استفاده می کند، خواه در سفر یا وسیله نقلیه کار کند. بخش پشتیبان Fleet Engine اطمینان می دهد که وسیله نقلیه قبل از انجام اصلاحات با سفر درخواستی مرتبط است.
Consumer SDK همیشه از ادعای tripid
استفاده می کند.
ارائه دهنده Rideshare یا Delivery باید از vehicleid
یا tripid
با یک "*" برای مطابقت با تمام وسایل نقلیه و سفرها استفاده کند. توجه داشته باشید که JWT میتواند حاوی هر دو نشانه باشد، حتی اگر مورد نیاز نباشد، که ممکن است اجرای امضای توکن را سادهتر کند.
موارد استفاده JWT
شکل زیر یک نمونه توکن برای سرور ارائه دهنده را نشان می دهد:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_provider_service_account"
}
.
{
"iss": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
شکل زیر نمونه ای از توکن برای برنامه مصرف کننده را نشان می دهد:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
شکل زیر نمونه ای از نشانه برای برنامه Driver را نشان می دهد:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- برای فیلد
kid
در هدر، شناسه کلید خصوصی حساب سرویس خود را مشخص کنید. می توانید این مقدار را در قسمتprivate_key_id
فایل JSON حساب سرویس خود بیابید. - برای فیلدهای
iss
وsub
، آدرس ایمیل حساب سرویس خود را مشخص کنید. می توانید این مقدار را در قسمتclient_email
فایل JSON حساب سرویس خود بیابید. - برای قسمت
aud
، https://SERVICE_NAME/ را مشخص کنید. - برای فیلد
iat
، از مهر زمانی هنگام ایجاد نشانه استفاده کنید، که به عنوان ثانیه های سپری شده از ساعت 00:00:00 UTC، 1 ژانویه 1970 مشخص شده است. 10 دقیقه برای انحراف زمان بگذارید. اگر مهر زمانی در گذشته یا در آینده خیلی دور باشد، سرور ممکن است خطا را گزارش کند. - برای فیلد
exp
، از مهر زمانی زمانی که نشانه منقضی میشود استفاده کنید، که به عنوان ثانیه از ساعت 00:00:00 UTC، 1 ژانویه 1970 مشخص شده است. حداکثر مقدار مجازiat
+ 3600 است.
هنگام امضای JWT برای انتقال به دستگاه تلفن همراه، مطمئن شوید که از حساب سرویس برای نقش Driver یا Consumer SDK استفاده میکنید. در غیر این صورت، دستگاه تلفن همراه توانایی تغییر حالتی را که نباید داشته باشد خواهد داشت.
به همین ترتیب، هنگام امضای JWT برای استفاده برای تماسهای ممتاز، مطمئن شوید که از حساب سرویس با نقش Super User استفاده میکنید. در غیر این صورت، عملیات شکست خواهد خورد.
تولید JWT برای آزمایش
تولید توکن ها از ترمینال می تواند هنگام آزمایش مفید باشد.
برای انجام این مراحل، حساب کاربری شما باید نقش ایجاد کننده رمز حساب کاربری را داشته باشد:
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
یک فایل جدید به نام unsigned_token.json
با محتوای زیر ایجاد کنید. ویژگی iat
زمان فعلی بر حسب ثانیه بعد از دوره است که با اجرای date +%s
در ترمینال شما قابل بازیابی است. ویژگی exp
زمان انقضا بر حسب ثانیه بعد از دوره است که با افزودن 3600 به iat
قابل محاسبه است. زمان انقضا در آینده نمی تواند بیش از یک ساعت باشد.
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
سپس دستور gcloud زیر را اجرا کنید تا رمز را از طرف حساب سرویس Super User خود امضا کنید:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
اکنون یک JWT رمزگذاری شده با Base64 امضا شده باید در فایل signed_token.jwt
ذخیره شود. ژتون برای یک ساعت بعد معتبر است.
اکنون می توانید توکن را با اجرای دستور curl
در مقابل نقطه پایانی List Vehicles REST آزمایش کنید:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
وسایل نقلیه و چرخه حیات آنها
Vehicle نهادی است که یک جفت راننده و وسیله نقلیه را نشان می دهد. در حال حاضر، راننده و وسیله نقلیه را نمی توان به طور جداگانه ردیابی کرد. ارائهدهنده Rideshare یا Delivery با استفاده از شناسه ارائهدهنده (که باید همان شناسه پروژه Google Cloud Project که حاوی حساب سرویس مورد استفاده برای فراخوانی APIهای Fleet Engine است) و یک شناسه خودرو متعلق به ارائهدهنده Rideshare یا تحویلدهنده باشد، وسیله نقلیه ایجاد میکند. .
خودرویی که پس از هفت روز از طریق UpdateVehicle
بهروزرسانی نشده باشد، بهطور خودکار حذف میشود. فراخوانی CreateVehicle
با یک جفت شناسه ارائه دهنده/شناسه وسیله نقلیه که از قبل وجود دارد یک خطا است. موارد وسایل نقلیهای که اغلب بهروزرسانی نمیشوند را میتوان به دو روش بررسی کرد: تماس مکرر CreateVehicle
با یک جفت شناسه ارائهدهنده/شناسه وسیله نقلیه مورد انتظار و حذف خطا در صورتی که خودرو از قبل وجود داشته باشد. یا، فراخوانی CreateVehicle
پس از بازگشت UpdateVehicle
با خطای NOT_FOUND
.
به روز رسانی مکان خودرو
برای بهترین عملکرد با Fleet Engine، جریانی از بهروزرسانیهای مکان خودرو را در اختیار آن قرار دهید. برای ارائه این به روز رسانی ها از یکی از راه های زیر استفاده کنید:
- از Driver SDK - Android ، iOS - ساده ترین گزینه استفاده کنید.
- از کد سفارشی استفاده کنید -- اگر مکانها از طریق باطن شما منتقل میشوند یا اگر از دستگاههایی غیر از Android یا iOS استفاده میکنید مفید است.
انواع وسایل نقلیه
موجودیت وسیله نقلیه حاوی یک فیلد الزامی از VehicleType
است که حاوی یک فهرست Category
است که می تواند به عنوان AUTO
، TAXI
، TRUCK
، TWO_WHEELER
، BICYCLE
یا PEDESTRIAN
مشخص شود. نوع وسیله نقلیه می تواند به عنوان یک معیار فیلتر در SearchVehicles
و ListVehicles
عمل کند.
اگر دسته روی AUTO
, TWO_WHEELER
, BICYCLE
یا PEDESTRIAN
تنظیم شده باشد , همه مسیریابی برای وسایل نقلیه از RouteTravelMode
مربوطه استفاده خواهد کرد . اگر دسته روی TAXI
یا TRUCK
تنظیم شود، مسیریابی مانند حالت AUTO
رفتار می شود.
ویژگی های وسیله نقلیه
نهاد Vehicle حاوی یک فیلد مکرر از VehicleAttribute
است. این ویژگی ها توسط Fleet Engine تفسیر نمی شوند. SearchVehicles
API شامل فیلدی است که الزام میکند Vehicles
منطبق باید شامل تمام ویژگیهای موجود در مقدار مشخص شده باشند.
توجه داشته باشید که فیلد مشخصه علاوه بر چندین فیلد پشتیبانی شده دیگر در پیام Vehicle
است، مانند vehicle_type
و supported_trip_types
.
ایستگاه های راه باقی مانده وسیله نقلیه
موجودیت وسیله نقلیه حاوی یک فیلد مکرر از TripWaypoint
( RPC | REST ) است که waypoints
( RPC | REST ) نامیده می شود. این فیلد به ترتیبی که وسیله نقلیه به آنها می رسد، نقاط بین راه را در سفرها شامل می شود. Fleet Engine این فیلد را زمانی که سفرها به وسیله نقلیه اختصاص مییابد محاسبه میکند و با تغییر وضعیت سفرها، آن را بهروزرسانی میکند. این نقاط را می توان با فیلد TripId
و فیلد WaypointType
شناسایی کرد.
گسترش واجد شرایط بودن یک وسیله نقلیه برای مسابقات
به طور معمول، خدمات Rideshare یا Delivery Provider مسئول مطابقت درخواستهای سفر با وسایل نقلیه است. این سرویس می تواند از ویژگی های خودرو برای گنجاندن یک وسیله نقلیه در تعداد بیشتری از جستجوها استفاده کند. برای مثال، ارائهدهنده میتواند مجموعهای از ویژگیهای مربوط به سطوح امتیازات یا قابلیتهای ارائهشده توسط یک وسیله نقلیه را پیادهسازی کند. به عنوان مثال، سه سطح می تواند مجموعه ای از ویژگی ها با مقادیر بولی باشد: is_bronze_level
، is_silver_level
و is_gold_level
. یک وسیله نقلیه می تواند برای هر سه واجد شرایط باشد. هنگامی که Fleet Engine درخواستی برای سفری دریافت می کند که به قابلیت های سطح نقره ای نیاز دارد، جستجو شامل آن وسیله نقلیه می شود. استفاده از ویژگی ها از این طریق شامل وسایل نقلیه ای می شود که قابلیت های مختلفی را ارائه می دهند.
دو راه برای به روز رسانی ویژگی های خودرو وجود دارد. یکی UpdateVehicle
API است. هنگام استفاده از این API، کل مجموعه ویژگی های خودرو روی مقدار تنظیم می شود. امکان به روز رسانی یک ویژگی واحد وجود ندارد. روش دیگر UpdateVehicleAttributes
API است. این روش فقط ویژگی هایی را برای به روز رسانی می گیرد. ویژگی های گنجانده شده در درخواست به مقدار جدید تنظیم می شود یا اضافه می شود. ویژگی های نامشخص تغییر نخواهند کرد.
چگونه: یک وسیله نقلیه بسازید
برای ردیابی هر خودرو در ناوگان باید یک نهاد Vehicle
ایجاد شود.
از نقطه پایانی CreateVehicle
با CreateVehicleRequest
برای ایجاد یک وسیله نقلیه استفاده کنید.
provider_id
Vehicle
باید شناسه پروژه (به عنوان مثال پروژه my-on-demand-پروژه) Google Cloud باشد که حاوی حسابهای خدماتی است که برای فراخوانی Fleet Engine استفاده میشود. توجه داشته باشید که اگرچه چندین حساب خدمات ممکن است به Fleet Engine برای یک Rideshare یا Delivery Provider دسترسی داشته باشند، Fleet Engine در حال حاضر از حسابهای خدماتی از چندین پروژه Google Cloud که به یک Vehicles
دسترسی دارند پشتیبانی نمیکند.
Vehicle
می توان در حالت OFFLINE
یا ONLINE
ایجاد کرد. در صورت ایجاد ONLINE
ممکن است فوراً در پاسخ به سؤالات SearchVehicles
برگردانده شود.
ممکن است یک last_location
اولیه در تماس CreateVehicle
گنجانده شود. در حالی که مجاز است، یک Vehicle
نباید در حالت ONLINE
بدون last_location
ایجاد شود.
برای جزئیات بیشتر در مورد فیلد نوع خودرو به انواع خودرو مراجعه کنید.
برای جزئیات بیشتر در مورد فیلد ویژگی ها به ویژگی های خودرو مراجعه کنید.
مقدار بازگشتی از CreateVehicle
، موجودیت Vehicle
ایجاد شده است.
مثال
پوسته
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "OFFLINE",
"supportedTripTypes": ["EXCLUSIVE"],
"maximumCapacity": 4,
"vehicleType": {"category": "AUTO"},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
مرجع ارائه دهنده ها.خودروها.ایجاد مرجع را ببینید.
جاوا
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService =
VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.OFFLINE) // Initial state
.addSupportedTripTypes(TripType.EXCLUSIVE)
.setMaximumCapacity(4)
.setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.addAttributes(VehicleAttribute.newBuilder()
.setKey("on_trip").setValue("false")) // Opaque to the Fleet Engine
// Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
// matching while even if it is on a trip. By default this is disabled.
.build();
CreateVehicleRequest createVehicleRequest =
CreateVehicleRequest.newBuilder() // no need for the header
.setParent(parent)
.setVehicleId("vid-8241890") // Vehicle ID assigned by Rideshare or Delivery Provider
.setVehicle(vehicle) // Initial state
.build();
// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided. When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.
try {
Vehicle createdVehicle =
vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle created successfully.
گزارشهای پلتفرم Google Cloud برای ایجاد خودرو
هنگامی که تماسی با نقطه پایانی CreateVehicle
دریافت میشود، Fleet Engine API یک ورودی گزارش از طریق گزارشهای پلتفرم Google Cloud مینویسد. ورودی گزارش شامل اطلاعاتی در مورد مقادیر در درخواست CreateVehicle
است. در صورت موفقیت آمیز بودن تماس، اطلاعات مربوط به Vehicle
برگشت داده شده را نیز شامل می شود.
پوسته
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'
باید رکوردی مشابه موارد زیر چاپ کنید:
---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
'@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
request:
vehicle:
attributes:
- key: on_trip
value: 'false'
maximumCapacity: 4
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
vehicleId: vid-8241890
response:
attributes:
- key: on_trip
value: 'false'
availableCapacity: 4
currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
maximumCapacity: 4
name: providers/project-id/vehicles/vid-8241890
state: VEHICLE_STATE_OFFLINE
supportedTrips:
- EXCLUSIVE_TRIP
vehicleType:
vehicleCategory: AUTO
labels:
vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
labels:
location: global
resource_container: projects/project-id
type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'
اعلانهای Cloud Pub/Sub برای ایجاد خودرو
Fleet Engine API یک اعلان از طریق Cloud Pub/Sub هنگام ایجاد یک وسیله نقلیه جدید منتشر می کند. برای دریافت این اعلانها، لطفاً دستورالعملهای اینجا را دنبال کنید.
نحوه انجام: به روز رسانی مکان وسیله نقلیه
اگر از Driver SDK برای بهروزرسانی مکان خودرو استفاده نمیکنید، میتوانید با مکان خودرو مستقیماً با Fleet Engine تماس بگیرید. برای هر وسیله نقلیه فعال، Fleet Engine انتظار دارد حداقل یک بار در هر دقیقه و حداکثر یک بار در هر 5 ثانیه یک به روز رسانی مکان انجام شود. این بهروزرسانیها فقط به امتیازات کاربر Fleet Engine Driver SDK نیاز دارند.
مثال
پوسته
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
"supplementalLocationTime": "$(date -u --iso-8601=seconds)",
"supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
"supplementalLocationAccuracy": 15
}
EOM
مرجع providers.vehicles.update را ببینید.
جاوا
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setLastLocation(VehicleLocation.newBuilder()
.setSupplementalLocation(LatLng.newBuilder()
.setLatitude(37.3382)
.setLongitude(121.8863))
.setSupplementalLocationTime(now())
.setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
.setSupplementalLocationAccuracy(DoubleValue.of(15.0))) // Optional)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("last_location"))
.build();
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
نحوه انجام: سایر فیلدهای خودرو را به روز کنید
بهروزرسانی سایر ویژگیهای حالت خودرو کمتر از بهروزرسانیهای موقعیت رخ میدهد. بهروزرسانی ویژگیهای غیر از last_location
به امتیازات Fleet Engine Super User نیاز دارد.
UpdateVehicleRequest
شامل یک update_mask
است که نشان می دهد کدام فیلدها باید به روز شوند. رفتار میدان مانند مستندات Protobuf برای ماسک های میدان است.
همانطور که در Vehicle Attributes اشاره شد، بهروزرسانی فیلد attributes
مستلزم نوشتن تمام ویژگیها است تا حفظ شود. در تماس UpdateVehicle
نمی توان فقط مقدار یک جفت کلید-مقدار را به روز کرد. برای بهروزرسانی مقادیر مشخصههای خاص، میتوان از UpdateVehicleAttributes
API استفاده کرد.
مثال
این مثال back_to_back
فعال می کند.
پوسته
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleState": "ONLINE",
"attributes": [
{"key": "on_trip", "value": "true"},
{"key": "cash_only", "value": "false"}
],
"backToBackEnabled": true
}
EOM
مرجع providers.vehicles.update را ببینید.
جاوا
static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
.setVehicleState(VehicleState.ONLINE)
.addAllAttributes(ImmutableList.of(
VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
.setBackToBackEnabled(true)
.build();
UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
.setName(vehicleName)
.setVehicle(updatedVehicle)
.setUpdateMask(FieldMask.newBuilder()
.addPaths("vehicle_state")
.addPaths("attributes")
.addPaths("back_to_back_enabled"))
.build();
// Attributes and vehicle state are being updated, so both are
// included in the field mask. Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.
try {
Vehicle updatedVehicle =
vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
// Most implementations will call CreateVehicle in this case
break;
case PERMISSION_DENIED:
break;
}
return;
}
// If no Exception, Vehicle updated successfully.
گزارشهای پلتفرم Google Cloud برای بهروزرسانیهای خودرو
هنگامی که تماسی با نقطه پایانی UpdateVehicle
دریافت میشود، Fleet Engine API یک ورودی گزارش از طریق گزارشهای پلتفرم Google Cloud مینویسد. ورودی گزارش شامل اطلاعاتی در مورد مقادیر در درخواست UpdateVehicle
است. در صورت موفقیت آمیز بودن تماس، اطلاعات مربوط به Vehicle
برگشت داده شده را نیز شامل می شود.
پوسته
gcloud --project=project-id logging read --freshness=1h '
jsonPayload.request.vehicleId="vid-8241890"
jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'
اعلانهای Cloud Pub/Sub برای بهروزرسانیهای خودرو
Fleet Engine API یک اعلان از طریق Cloud Pub/Sub هنگامی که یک وسیله نقلیه موجود به روز می شود منتشر می کند. برای دریافت این اعلانها، لطفاً دستورالعملهای اینجا را دنبال کنید.
روش: وسایل نقلیه را جستجو کنید
Fleet Engine از جستجوی وسایل نقلیه پشتیبانی می کند. SearchVehicles
API به شما امکان می دهد درایورهای موجود در نزدیکی را بیابید که برای کارهایی مانند سرویس یک سواری یا درخواست تحویل مناسب هستند. SearchVehicles
API فهرست رتبه بندی شده ای از رانندگان را برمی گرداند که ویژگی های وظیفه را با ویژگی های وسایل نقلیه در ناوگان شما مطابقت می دهند. برای اطلاعات بیشتر، به یافتن درایورهای نزدیک مراجعه کنید.
مثال
هنگام جستجوی وسایل نقلیه موجود، Fleet Engine به طور پیش فرض وسایل نقلیه در سفرهای فعال را حذف می کند. خدمات Rideshare یا Delivery Provider باید به صراحت آنها را در درخواست های جستجو لحاظ کند. مثال زیر نشان میدهد که چگونه میتوان آن وسایل نقلیه را در جستجوی وسایل نقلیه منطبق با سفر از مرکز خرید بزرگ اندونزی شرقی به مرکز همایش Balai Sidang جاکارتا گنجاند.
پوسته
ابتدا مکان وسیله نقلیه ای را که در مراحل قبلی ایجاد کردیم به روز کنید تا واجد شرایط باشد. در دنیای واقعی، این کار توسط Driver SDK که روی دستگاه اندروید یا iOS در خودرو اجرا میشود، انجام میشود.
curl -X PUT \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"lastLocation": {
"updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
"location": {
"latitude": "-6.195139",
"longitude": "106.820826"
}
},
"attributes": [{"key": "on_trip", "value": "false"}]
}
EOM
انجام جستجو باید حداقل آن وسیله نقلیه را به دست آورد.
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
},
"pickupRadiusMeters": 2000,
"count": 10,
"minimumCapacity": 2,
"tripTypes": ["EXCLUSIVE"],
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
"orderBy": "PICKUP_POINT_ETA",
"includeBackToBack": true
}
EOM
مرجع providers.vehicles.search را ببینید.
جاوا
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
.setParent(parent)
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
.setDropoffPoint( // Balai Sidang Jakarta Convention Center
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
.setPickupRadiusMeters(2000)
.setCount(10)
.setMinimumCapacity(2)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
SearchVehiclesResponse searchVehiclesResponse =
vehicleService.searchVehicles(searchVehiclesRequest);
// Search results: Each vehicle match contains a vehicle entity and information
// about the distance and ETA to the pickup point and dropoff point.
List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
پرس و جو فیلترینگ خودرو
SearchVehicles
و ListVehicles
از فیلتر کردن ویژگیهای خودرو با استفاده از جستجوی فیلتر پشتیبانی میکنند. برای نحو پرس و جو فیلتر، برای مثال AIP-160 را ببینید.
توجه داشته باشید که درخواستهای فیلتر فقط از فیلتر کردن ویژگیهای خودرو پشتیبانی میکنند و نمیتوانند برای فیلدهای دیگر استفاده شوند. پرس و جو فیلتر به عنوان یک بند AND
با محدودیت های دیگر، مانند minimum_capacity
یا vehicle_types
در SearchVehiclesRequest
عمل می کند.
نحوه انجام: فهرست وسایل نقلیه
SearchVehicles
برای یافتن تعداد کمی از وسایل نقلیه به ترتیب رتبه بندی شده خیلی سریع بهینه شده است و عمدتاً برای یافتن رانندگان نزدیک که برای یک کار مناسب هستند استفاده می شود. با این حال، گاهی اوقات می خواهید همه وسایل نقلیه ای را پیدا کنید که برخی از معیارها را برآورده می کنند، حتی اگر صفحه بندی نتایج ضروری باشد. ListVehicles
برای این مورد طراحی شده است.
ListVehicles
API به شما امکان می دهد تمام وسایل نقلیه ای را پیدا کنید که برخی از گزینه های درخواستی خاص را برآورده می کنند. ListVehicles
API فهرست صفحه بندی شده ای از وسایل نقلیه در پروژه را برمی گرداند که با برخی از الزامات مطابقت دارد.
برای فیلتر کردن ویژگیهای خودرو، لطفاً به جستار فیلترینگ خودرو مراجعه کنید.
مثال
این مثال فیلتر کردن vehicle_type
و ویژگی ها را با استفاده از رشته filter
انجام می دهد.
پوسته
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"vehicleTypes": [{"category": "AUTO"}],
"filter": "attributes.on_trip=\"false\"",
}
EOM
مرجع providers.vehicles.list را ببینید.
جاوا
static final String PROJECT_ID = "project-id";
VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
.setParent(parent)
.addTripTypes(TripType.EXCLUSIVE)
.addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
.setFilter("attributes.on_trip=\"false\"")
.setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
.build();
// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully
try {
ListVehiclesResponse listVehiclesResponse =
vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case NOT_FOUND:
break;
case PERMISSION_DENIED:
break;
}
return;
}
سفرها و چرخه زندگی آنها
Trip API و lifecycle مشابه Vehicle API و lifecycle است. ارائه دهنده Rideshare مسئول ایجاد سفرها با استفاده از رابط های Fleet Engine است. Fleet Engine هر دو سرویس RPC، TripService
، و منابع REST، provider.trips
را ارائه می دهد. این رابطها ایجاد Trip entity، درخواستهای اطلاعات، قابلیت جستجو و قابلیت بهروزرسانی را فعال میکنند.
یک Trip
دارای یک فیلد وضعیت برای ردیابی پیشرفت آن در طول چرخه حیات است. مقادیر از NEW
به COMPLETE
به اضافه CANCELED
و UNKNOWN_TRIP_STATUS
منتقل می شوند. به trip_status
برای RPC یا TripStatus برای REST مراجعه کنید.
-
NEW
-
ENROUTE_TO_PICKUP
-
ARRIVED_AT_PICKUP
-
ENROUTE_TO_INTERMEDIATE_DESTINATION
-
ARRIVED_AT_INTERMEDIATE_DESTINATION
-
ENROUTE_TO_DROPOFF
-
COMPLETE
سرویس شما میتواند سفر را از هر یک از این وضعیتها به CANCELED
بهروزرسانی کند. وقتی سرویس شما یک سفر ایجاد می کند، موتور وضعیت را به عنوان NEW
تنظیم می کند. vehicle_id
اختیاری است. مانند وسایل نقلیه، سرویسها پس از هفت روز بدون بهروزرسانی، سفرها را بهطور خودکار حذف میکنند. اگر سرویس شما سعی کند سفری را با شناسه ای که از قبل وجود دارد ایجاد کند، خطایی برگردانده می شود. اگر یک سفر در وضعیتی غیر از COMPLETE
یا CANCELED
شده باشد، "فعال" در نظر گرفته می شود. این تمایز در قسمت active_trips
موجود در Vehicle entity و SearchTripsRequest
مهم است.
این سرویس تنها زمانی میتواند vehicle_id
اختصاص داده شده به یک سفر را تغییر دهد که وضعیت NEW
یا CANCELED
باشد. اگر راننده در حین مسیر سفری را لغو کند، وضعیت سفر باید قبل از تغییر یا پاک شدن vehicle_id
روی NEW
یا CANCELED
تنظیم شود.
وضعیت هنگام اجرای پشتیبانی از سفر پشت سر هم مهم است. این پشتیبانی ارائهدهنده را قادر میسازد تا زمانی که آن وسیله نقلیه در سفر فعال است، سفر جدیدی را به یک وسیله نقلیه اختصاص دهد. کد ایجاد یک سفر پشت سر هم مانند یک سفر است و از همان شناسه وسیله نقلیه استفاده می کند. Fleet Engine مبدا و مقصد سفر جدید را به نقاط بین راهی خودرو اضافه می کند. برای اطلاعات بیشتر درباره سفرهای پشت سر هم، به ایجاد سفرهای چندراهی مراجعه کنید.
ایستگاه های بین راهی باقی مانده سفر
موجودیت Trip حاوی یک فیلد مکرر از TripWaypoint
( RPC | REST ) است که به آن remainingWaypoints
( RPC | REST ) میگویند. این فیلد شامل تمام نقاط بین راهی است که وسیله نقلیه باید به ترتیب قبل از خروج نهایی این سفر طی کند. از ایستگاه های باقی مانده وسیله نقلیه محاسبه می کند. در موارد استفاده Back-to-Back و Carpool، این لیست حاوی نقاط بین سفرهای دیگری است که قبل از این سفر از آنها عبور می شود، اما هر نقطه بین راهی بعد از این سفر را استثنا نمی کند. نقطه راه در لیست را می توان با TripId
و WaypointType
آن شناسایی کرد.
رابطه بین وضعیت سفر و ایستگاه های بین راهی باقی مانده وسیله نقلیه
زمانی که Fleet Engine درخواست تغییر وضعیت سفر را دریافت کرد ، نقاط بین راهی خودرو ( RPC | REST ) بهروزرسانی میشوند. هنگامی که tripStatus
( RPC | REST ) از وضعیت دیگر به ENROUTE_TO_XXX تغییر یابد، نقطه بین راه قبلی از لیست نقاط باقیمانده خودرو حذف خواهد شد. یعنی زمانی که وضعیت سفر از ENROUTE_TO_PICKUP به ARRIVED_AT_PICKUP تغییر میکند، نقطه تحویل سفر همچنان در لیست ایستگاههای باقیمانده خودرو خواهد بود، اما وقتی وضعیت سفر به ENROUTE_TO_INTERMEDIATE_DESTINATION یا ENROUTE_TO_DROPOFF تغییر میکند، پس از آن، نقطه تحویل از وسیله نقلیه حذف میشود.
این برای ARRIVED_AT_INTERMEDIATE_DESTINATION و ENROUTE_TO_INTERMDEDIATE_DESTINATION یکسان است. هنگامی که ARRIVED_AT_INTERMEDIATE_DESTINATION، مقصد میانی کنونی از لیست ایستگاه های بین راهی خودرو حذف نمی شود تا زمانی که خودرو گزارش دهد که به سمت ایستگاه بین راهی بعدی می رود.
وقتی وضعیت سفر به COMPLETED
تغییر میکند، هیچ نقطهای از این سفر در فهرست ایستگاههای باقیمانده خودرو نخواهد بود.
نحوه انجام: یک سفر ایجاد کنید
یک نهاد Trip
باید ایجاد شود تا هر درخواست سفر ردیابی شود و با وسایل نقلیه موجود در ناوگان مطابقت داده شود. از نقطه پایانی CreateTrip
با CreateTripRequest
برای ایجاد یک سفر استفاده کنید.
ویژگی های زیر برای ایجاد یک سفر مورد نیاز است:
-
parent
- رشته ای که شامل شناسه ارائه دهنده است که هنگام ایجاد پروژه Google Cloud ایجاد شده است. -
trip_id
- رشته ای که توسط ارائه دهنده Rideshare ایجاد شده است. -
trip
- کانتینری با ابرداده اصلی که سفر را توصیف می کند.
هنگام ایجاد سفر، میتوانید number_of_passengers
، dropoff_point
و vehicle_id
را ارائه دهید. اگرچه این فیلدها الزامی نیستند، اما اگر آنها را ارائه کنید، حفظ می شوند. همه فیلدهای سفر دیگر نادیده گرفته می شوند. به عنوان مثال، همه سفرها با یک trip_status
NEW
شروع میشوند، حتی اگر در درخواست ایجاد یک trip_status
CANCELED
عبور کنید.
مثال
مثال زیر سفری به مرکز خرید بزرگ اندونزی شرقی ایجاد می کند. این سفر دو نفره و اختصاصی است. provider_id
Trip
باید با شناسه پروژه یکی باشد. در مثال، ارائهدهنده Rideshare پروژه Google Cloud، project-id ایجاد کرد. این پروژه باید دارای حساب های سرویس مورد استفاده برای فراخوانی Fleet Engine باشد. وضعیت سفر NEW
است.
بعداً، پس از اینکه سرویس با سفر به وسیله نقلیه مطابقت داشت، سرویس میتواند با UpdateTrip
تماس بگیرد و هنگامی که سفر به یک وسیله نقلیه اختصاص داده شد، vehicle_id
تغییر دهد.
پوسته
curl -X POST \
"https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
--data-binary @- << EOM
{
"tripType": "EXCLUSIVE",
"numberOfPassengers": 2,
"pickupPoint": {
"point": {"latitude": "-6.195139", "longitude": "106.820826"}
},
"dropoffPoint": {
"point": {"latitude": "-6.1275", "longitude": "106.6537"}
}
}
EOM
مرجع providers.trips.create را ببینید.
جاوا
static final String PROJECT_ID = "project-id";
TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);
String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
.setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
.setPickupPoint( // Grand Indonesia East Mall
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
// Provide the number of passengers if available.
.setNumberOfPassengers(2)
// Provide the drop-off point if available.
.setDropoffPoint(
TerminalLocation.newBuilder().setPoint(
LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
.build();
CreateTripRequest createTripRequest =
CreateTripRequest.newBuilder() // no need for the header
.setParent(parent)
.setTripId("tid-1f97") // Trip ID assigned by the Provider
.setTrip(trip) // Initial state
.build();
// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.
try {
Trip createdTrip =
tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
Status s = e.getStatus();
switch (s.getCode()) {
case ALREADY_EXISTS:
break;
case PERMISSION_DENIED:
break;
}
return;
}
گزارشهای پلتفرم Google Cloud برای Trip Creation
هنگامی که تماسی با نقطه پایانی CreateTrip
دریافت میشود، Fleet Engine API یک ورودی گزارش را با استفاده از گزارشهای پلتفرم Google Cloud مینویسد. ورودی گزارش شامل اطلاعاتی در مورد مقادیر در درخواست CreateTrip
است. در صورت موفقیت آمیز بودن تماس، اطلاعات مربوط به Trip
که برگردانده شده است نیز خواهد بود.
نحوه انجام: یک سفر را به روز کنید
موجودیت سفر حاوی فیلدهایی است که امکان ردیابی توسط سرویس و گزارش پیشرفت سفر توسط Driver SDK و Consumer SDK را فراهم می کند. برای به روز رسانی ویژگی ها، از پیام UpdateTripRequest
استفاده کنید. این فیلدهای Trip را مطابق با field_mask
درخواست به روز می کند. به UpdateTripRequest مراجعه کنید.
ارائه دهنده Rideshare مسئول به روز رسانی ویژگی های زیر است:
- وضعیت سفر
- شناسه خودرو چه در زمان ایجاد، یا پس از تطبیق وسیله نقلیه با یک سفر.
- تغییرات در مسیرهای تحویل، خروج یا ایستگاه های بین راه.
هنگام استفاده از ویژگی Journey Sharing از طریق Driver SDK یا Consumer SDK، Fleet Engine به طور خودکار فیلدهای زیر را به روز می کند:
- مسیرها
- ETA
- فاصله باقی مانده
- مکان وسیله نقلیه
- نقاط بین راه
به Trip
in RPC یا Resource.Trip
in REST مراجعه کنید.
گزارشهای پلتفرم Google Cloud برای بهروزرسانیهای سفر
هنگامی که تماسی با نقطه پایانی UpdateTrip
دریافت می شود، Fleet Engine API یک ورودی گزارش را با استفاده از گزارش های پلت فرم Google Cloud می نویسد. ورودی گزارش شامل اطلاعاتی در مورد مقادیر در درخواست UpdateTrip
است. در صورت موفقیت آمیز بودن تماس، اطلاعات مربوط به Trip
که برگردانده شده است نیز خواهد بود.
نحوه انجام: جستجوی سفرها
Fleet Engine از جستجوی سفرها پشتیبانی می کند. همانطور که قبلا ذکر شد، یک سفر به طور خودکار پس از هفت روز حذف می شود، بنابراین SearchTrips
تاریخچه کامل همه سفرها را نشان نمی دهد.
در حالی که SearchTrips
یک API انعطاف پذیر است، لیست زیر دو مورد استفاده را در نظر می گیرد.
تعیین سفرهای فعال وسیله نقلیه - ارائه دهنده می تواند سفرهای فعال فعلی یک وسیله نقلیه را تعیین کند. در
SearchTripsRequest
،vehicle_id
روی خودروی مورد بررسی تنظیم می شود وactive_trips_only
باید رویtrue
تنظیم شود.تطبیق وضعیت ارائه دهنده و موتور ناوگان -- ارائه دهنده می تواند از
SearchTrips
برای اطمینان از مطابقت وضعیت سفر خود و موتور ناوگان استفاده کند. این به ویژه برای TripStatus مهم است. اگر وضعیت یک سفر اختصاص داده شده به یک وسیله نقلیه به درستی رویCOMPLETE
یاCANCELED
تنظیم نشده باشد، وسیله نقلیه توسطSearchVehicles
لحاظ نمی شود.
برای استفاده از SearchTrips
در این روش، vehicle_id
خالی بگذارید، active_trips_only
روی true
تنظیم کنید، و minimum_staleness
را روی زمانی بیشتر از مدت زمان سفر تنظیم کنید. به عنوان مثال، شما ممکن است یک ساعت استفاده کنید. نتایج شامل سفرهایی میشود که کامل یا لغو نشدهاند و در مدت بیش از یک ساعت بهروزرسانی نشدهاند. ارائه دهنده باید این سفرها را بررسی کند تا مطمئن شود که وضعیت آنها در موتور ناوگان به درستی به روز شده است.
عیب یابی
در مورد خطای DEADLINE_EXCEEDED
، وضعیت موتور ناوگان ناشناخته است. ارائهدهنده باید دوباره CreateTrip
فراخوانی کند که یا 201 (CREATED) یا 409 (CONFLICT) را برمیگرداند. در مورد دوم، درخواست قبلی قبل از DEADLINE_EXCEEDED
با موفقیت انجام شد. برای اطلاعات بیشتر در مورد رسیدگی به خطاهای سفر: Android یا iOS به راهنمای مصرفکننده API مراجعه کنید.
پشتیبانی از سواری کارپول
می توانید چندین سفر SHARED
را به وسیله نقلیه ای اختصاص دهید که از TripType.SHARED
پشتیبانی می کند. هنگام اختصاص دادن vehicle_id
برای یک سفر مشترک (در یک درخواست CreateTrip
یا UpdateTrip
) باید ترتیب تمام نقاط بین راه را برای همه سفرهای اختصاص داده شده به وسیله نقلیه در این سفر مشترک از طریق Trip.vehicle_waypoints
مشخص کنید. برای RPC به vehicle_waypoints
برای RPC یا vehicleWaypoints
برای REST مراجعه کنید.
پشتیبانی از چندین مقصد
مقصد میانی را مشخص کنید
فیلد intermediateDestinations
و فیلد intermediateDestinationIndex
در Trip ( RPC | REST ) برای نشان دادن مقصد ترکیب شدهاند.
مقصد میانی را بهروزرسانی کنید
می توانید مقصدهای میانی را از طریق UpdateTrip
به روز کنید. هنگام بهروزرسانی مقصدهای میانی، باید فهرست کاملی از مقاصد میانی، از جمله مقصدهایی که بازدید شدهاند، ارائه کنید، نه فقط مقصدهایی که به تازگی اضافه شده یا باید اصلاح شوند. هنگامی که intermediateDestinationIndex
به شاخصی بعد از موقعیت مقصد میانی تازه اضافه شده/تغییر شده اشاره می کند، مقصد میانی جدید/به روز شده به waypoints
خودرو یا remainingWaypoints
سفر اضافه نمی شود. دلیل آن این است که هر مقصد میانی قبل از intermediateDestinationIndex
به عنوان بازدید شده قبلی در نظر گرفته می شود.
وضعیت سفر تغییر می کند
فیلد intermediateDestinationsVersion
in ( RPC | REST ) در درخواست بهروزرسانی وضعیت سفر که به Fleet Engine ارسال میشود، لازم است تا نشان دهد مقصد میانی گذشته است. مقصد میانی مورد نظر از طریق فیلد intermediateDestinationIndex
مشخص می شود. وقتی tripStatus
( RPC | 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 با مهندس مشتری خود تماس بگیرید یا با مهندس مشتری خود تماس بگیرید.
برای ایجاد موضوعی در پروژه ابری خود ، این دستورالعمل ها را دنبال کنید. شناسه موضوع باید "fleet_engine_notifications" باشد.
موضوع باید در همان پروژه ابری ایجاد شود که API های موتور ناوگان را فراخوانی می کند.
پس از ایجاد موضوع ، شما باید به API موتور ناوگان اجازه انتشار موضوع را بدهید. برای انجام این کار ، روی موضوعی که تازه ایجاد کرده اید کلیک کرده و مجوز جدیدی اضافه کنید. ممکن است برای باز کردن ویرایشگر مجوزها روی پانل اطلاعاتی کلیک کنید. اصلی باید geo-fleet-engine@system.gserviceaccount.com
باشد و نقش باید Pub/Sub publisher
باشد.
به منظور راه اندازی پروژه ابری خود برای عضویت در اعلان ها ، این دستورالعمل ها را دنبال کنید
API موتور ناوگان هر اعلان را در دو قالب داده مختلف ، protobuf
و json
منتشر می کند. قالب داده برای هر اعلان در ویژگی های pubsubmessage با کلید به عنوان data_format
و مقدار به عنوان protobuf
یا json
مشخص شده است.
طرح اعلان:
پروتوبوف
// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
// Required. At least one notification must exist.
// List of notifications containing information related to changes in
// Fleet Engine data.
repeated Notification notifications = 1;
}
// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
// Required. At least one type must exist.
// Type of notification.
oneof type {
// Notification related to changes in vehicle data.
VehicleNotification vehicle_notification = 1;
}
}
// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
// Required.
// Vehicle must contain all fields that were set when it was created.
Vehicle vehicle = 1;
}
// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
// Required.
// Vehicle must only contain name and fields that are present in the
// field_mask field below.
Vehicle vehicle = 1;
// Required.
// Contains vehicle field paths that were specifically requested
// by the Provider.
google.protobuf.FieldMask field_mask = 2;
}
// Notification related to changes in vehicle data.
message VehicleNotification {
// Required. At least one type must be set.
// Type of notification.
oneof type {
// Notification sent when a new vehicle was created.
CreateVehicleNotification create_notification = 1;
// Notification sent when an existing vehicle is updated.
UpdateVehicleNotification update_notification = 2;
}
}
JSON
BatchNotification: {
"description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
"type": "object",
"required": ["notifications"],
"properties": {
"notifications": {
"description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
"type": "Notification[]"
}
}
}
Notification: {
"description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
"type": "object",
"properties": {
"vehicleNotification": {
"description": "Notification related to changes in vehicle data.",
"type": "VehicleNotification"
}
}
}
VehicleNotification: {
"description": "Notification related to changes in vehicle data.",
"type": "object",
"properties": {
"createNotification": {
"description": "Notification sent when a new vehicle was created.",
"type": "CreateVehicleNotification"
},
"updateNotification": {
"description": "Notification sent when an existing vehicle is updated.",
"type": "UpdateVehicleNotification"
}
}
}
CreateVehicleNotification: {
"description": "Notification sent when a new vehicle was created.",
"type": "object",
"required": ["vehicle"],
"properties": {
"vehicle": {
"description": "Vehicle must contain all fields that were set when it was created.",
"type": "Vehicle"
}
}
}
UpdateVehicleNotification: {
"description": "Notification sent when an existing vehicle is updated.",
"type": "object",
"required": ["vehicle", "fieldMask"],
"properties": {
"vehicle": {
"description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
"type": "Vehicle"
},
"fieldMask": {
"description": "Contains vehicle field paths that were specifically requested by the Provider.",
"type": "FieldMask"
}
}
}
،موتور ناوگان در صورت تقاضا و تحویل API به شما امکان می دهد سفرها و وضعیت وسیله نقلیه را برای سفر خود مدیریت کنید و برنامه های پیشرفت را سفارش دهید. این معاملات بین Driver SDK ، Consumer SDK و سرویس پس زمینه شما را انجام می دهد - که می تواند با برقراری تماس GRPC یا استراحت با موتور ناوگان ارتباط برقرار کند.
پیش نیازها
برای توسعه ، اطمینان حاصل کنید که Cloud SDK (GCLOUD) را نصب کرده اید و به پروژه خود تأیید شده اید.
پوسته
gcloud auth login
شما باید یک پیام موفقیت آمیز مانند:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
بررسی کنید که API های موتور ناوگان راه حل در صورت تقاضا و تحویل ، به طور مناسب پیکربندی شده اند.
پوسته
gcloud --project=project-id services enable fleetengine.googleapis.com
اگر این دستور به خطایی منجر می شود ، برای دسترسی به مدیر پروژه و نماینده پشتیبانی Google خود مراجعه کنید.
ورود به سیستم
موتور ناوگان می تواند پیام های ورود به سیستم را در مورد تماس های API که در Google Cloud Platform دریافت می کند ، بنویسد. برای مرور کلی در مورد نحوه خواندن و تجزیه و تحلیل سیاههها ، مستندات ورود به سیستم Cloud را مشاهده کنید.
ورود به سیستم ممکن است به طور پیش فرض برای پروژه های ایجاد شده قبل از 10 فوریه 2022 فعال شود. برای اطلاعات بیشتر به اسناد ورود به سیستم مراجعه کنید.
کتابخانه های مشتری
ما کتابخانه های مشتری را در چندین زبان برنامه نویسی مشترک منتشر می کنیم. این کتابخانه ها به ارائه تجربه بهتر توسعه دهنده نسبت به استراحت خام یا GRPC کمک می کنند. برای راهنمایی در مورد نحوه به دست آوردن کتابخانه های مشتری برای برنامه سرور خود ، به کتابخانه های مشتری مراجعه کنید.
نمونه های جاوا در این مستندات ، آشنایی با GRPC را فرض می کنند.
احراز هویت و مجوز
می توانید قابلیت های ارائه شده از طریق سفر را پیکربندی کنید و از طریق کنسول Google Cloud پیشرفت کنید. این API ها و SDK ها به استفاده از نشانه های وب JSON که با استفاده از حساب های سرویس ایجاد شده از کنسول ابری امضا شده اند ، نیاز دارند.
تنظیم پروژه ابری
برای تنظیم پروژه ابری خود ، ابتدا پروژه خود را ایجاد کرده و سپس حسابهای سرویس ایجاد کنید.
برای ایجاد پروژه Google Cloud خود:
- با استفاده از کنسول Google Cloud یک پروژه Google Cloud ایجاد کنید.
- با استفاده از داشبورد 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:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.consumerSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.driverSdkUser gcloud --project=project-id iam service-accounts create fleet-engine-su gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \ --role=roles/fleetengine.serviceSuperUser
SDK های راننده و مصرف کننده در اطراف این نقش های استاندارد ساخته شده اند.
از طرف دیگر ، می توان نقش های سفارشی را ایجاد کرد که اجازه می دهد مجموعه ای از مجوزها به صورت دلخواه در کنار هم قرار بگیرند. راننده و SDK های مصرف کننده هر زمان که مجوز لازم از دست نرود ، پیام های خطا را نشان می دهند. در نتیجه ، ما اکیداً توصیه می کنیم از مجموعه استاندارد نقشهای ارائه شده در بالا و استفاده نکردن از نقش های سفارشی استفاده کنیم.
برای راحتی ، در صورت نیاز به ایجاد نشانه های JWT برای مشتری های غیر قابل اعتماد ، اضافه کردن کاربران به نقش سازنده توکن سرویس خدمات به آنها اجازه می دهد تا با ابزارهای خط فرمان GCLOUD نشانه هایی ایجاد کنند.
gcloud projects add-iam-policy-binding project-id \
--member=user:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
جایی که my-user@example.com
ایمیلی است که برای تأیید اعتبار با GCLOUD ( gcloud auth list --format='value(account)'
استفاده می شود).
ناوگان موتور کتابخانه AUT
Fleet Engine از نشانه های وب JSON (JWTS) برای محدود کردن دسترسی به API های موتور ناوگان استفاده می کند. کتابخانه جدید موتور ناوگان ، که در GitHub موجود است ، ساخت JWT های موتور ناوگان را ساده می کند و آنها را به طور ایمن امضا می کند.
این کتابخانه مزایای زیر را ارائه می دهد:
- روند ایجاد نشانه های موتور ناوگان را ساده می کند.
- مکانیسم های امضای توکن غیر از استفاده از پرونده های اعتبار (مانند جعل هویت یک حساب سرویس) را فراهم می کند.
- نشانه های امضا شده را به درخواست های برون مرزی که از یک خرد خرد GRPC یا مشتری GAPIC ساخته شده است ، پیوست می کند.
ایجاد یک توکن وب 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": "provider@yourgcpproject.iam.gserviceaccount.com",
"sub": "provider@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "*",
"tripid": "*"
}
}
موارد زیر یک نمونه نمونه برای برنامه مصرف کننده را نشان می دهد:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_consumer_service_account"
}
.
{
"iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
"sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"tripid": "trip_54321"
}
}
موارد زیر یک نمونه نمونه برای برنامه درایور را نشان می دهد:
{
"alg": "RS256",
"typ": "JWT",
"kid": "private_key_id_of_driver_service_account"
}
.
{
"iss": "driver@yourgcpproject.iam.gserviceaccount.com",
"sub": "driver@yourgcpproject.iam.gserviceaccount.com",
"aud": "https://fleetengine.googleapis.com/",
"iat": 1511900000,
"exp": 1511903600,
"authorization": {
"vehicleid": "driver_12345"
}
}
- برای
kid
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:my-user@example.com \
--role=roles/iam.serviceAccountTokenCreator
با محتوای زیر یک فایل جدید به نام unsigned_token.json
ایجاد کنید. خاصیت iat
زمان فعلی تعداد ثانیه پس از دوره است که می توان با اجرای date +%s
در ترمینال شما بازیابی کرد. خاصیت exp
در تعداد چند ثانیه پس از دوره ، زمان انقضا است که می توان با اضافه کردن 3600 به iat
محاسبه کرد. زمان انقضا نمی تواند بیش از یک ساعت در آینده باشد.
{ "aud": "https://fleetengine.googleapis.com/", "iss": "super-user-service-account@project-id.iam.gserviceaccount.com", "sub": "super-user-service-account@project-id.iam.gserviceaccount.com", "iat": iat, "exp": exp, "authorization": { "vehicleid": "*", "tripid": "*" } }
سپس دستور gcloud زیر را اجرا کنید تا نشانه را به نمایندگی از حساب خدمات فوق العاده کاربری خود امضا کنید:
gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt
JWT رمزگذاری شده Base64 امضا شده اکنون باید در پرونده signed_token.jwt
ذخیره شود. توکن برای ساعت بعد معتبر است.
اکنون می توانید با اجرای یک دستور curl
در برابر لیست وسایل نقلیه لیست ، توکن را آزمایش کنید:
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
.
به روزرسانی موقعیت مکانی وسیله نقلیه
برای بهترین عملکرد با موتور ناوگان ، جریانی از به روزرسانی های موقعیت مکانی وسیله نقلیه را در اختیار آن قرار دهید. از هر یک از روشهای زیر برای ارائه این به روزرسانی ها استفاده کنید:
- از درایور SDK - Android ، iOS - ساده ترین گزینه استفاده کنید.
- از کد سفارشی استفاده کنید - اگر مکانها از طریق پس زمینه شما منتقل می شوند ، یا اگر از دستگاه های دیگری غیر از 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
استفاده کنید.
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 برای ماسک های میدانی است.
همانطور که در ویژگی های وسیله نقلیه ذکر شد ، به روزرسانی قسمت 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
عمل می کند.
چگونه به: لیست وسایل نقلیه
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
شود.
وضعیت هنگام اجرای پشتیبانی از پشت به عقب از اهمیت برخوردار است. این پشتیبانی ارائه دهنده را قادر می سازد تا در حالی که آن وسیله نقلیه در یک سفر فعال قرار دارد ، سفر جدیدی را به وسیله نقلیه اختصاص دهد. کد برای ایجاد یک سفر برگشت به عقب همان سفر واحد است و از همان شناسه وسیله نقلیه استفاده می کند. موتور ناوگان منشأ و مقصد سفر جدید را به نقاط راه وسیله نقلیه اضافه می کند. برای کسب اطلاعات بیشتر در مورد سفرهای برگشت به عقب ، به ایجاد سفرهای چند واسطه مراجعه کنید.
سفر به ایستگاه های راه باقی مانده
نهاد سفر حاوی یک زمینه مکرر از 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
عبور کنید.
مثال
مثال زیر سفری به بازار گراند اندونزی شرقی ایجاد می کند. این سفر برای دو مسافر است و منحصر به فرد است. 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 مراجعه کنید.
ارائه دهنده 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
مراجعه کنید.
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.
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 geo-fleet-engine@system.gserviceaccount.com
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
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"
}
}
}