تتيح لك واجهة برمجة تطبيقات الرحلات عند الطلب عند الطلب من Fleet Engine إدارة الرحلات وحالة المركبة لتطبيقات "مسار الطلب" و"الرحلات". فهي تعالج المعاملات بين حزمة Driver SDK وحزمة تطوير البرامج (SDK) للمستهلك خدمة الخلفية التي يمكنها الاتصال بـ Fleet Engine من خلال إما gRPC أو مكالمات REST
المتطلبات الأساسية
لإجراء تطوير، احرص على تثبيت السحابة الإلكترونية SDK (gcloud) وتتم المصادقة عليها مع لمشروعك.
shell
gcloud auth login
من المفترض أن تظهر لك رسالة نجاح مثل:
You are now logged in as [my-user@example.com].
Your current project is [project-id]. You ...
تأكَّد من أنّه قد تم ضبط واجهات برمجة تطبيقات الرحلات عند الطلب وتسليمات الحلول Fleet Engine بشكل مناسب.
shell
gcloud --project=project-id services enable fleetengine.googleapis.com
إذا نتج عن هذا الأمر خطأ، يُرجى الرجوع إلى مشرف المشروع وممثل دعم Google الذي تتعامل معه للحصول على إذن الوصول.
التسجيل
يمكن لجهاز Fleet Engine كتابة رسائل سجلّ طلبات البيانات من واجهة برمجة التطبيقات التي يتلقّاها. إلى سجلات Google Cloud Platform يمكنك الاطّلاع على مستندات التسجيل في السحابة الإلكترونية حول نظرة عامة على كيفية قراءة وتحليل السجلات.
قد لا يكون التسجيل مُفعَّلاً تلقائيًا للمشاريع التي تم إنشاؤها قبل 10 شباط (فبراير) 2022. يمكنك الاطّلاع على مستندات التسجيل لمزيد من التفاصيل.
مكتبات العملاء
وننشر مكتبات العملاء بعدة لغات برمجة شائعة. هذه الاستعانة بالمكتبات في توفير تجربة أفضل للمطوّرين مقارنةً بـ REST أو gRPC الأوّلي. للحصول على تعليمات حول كيفية الحصول على مكتبات العملاء لتطبيق الخادم الخاص بك، الرؤية مكتبات العميل:
تفترض أمثلة Java في هذه الوثائق الإلمام بـ gRPC.
المصادقة والترخيص
يمكنك ضبط الإمكانات التي يوفّرها مستوى تقدّم الرحلات والطلبات من خلال Google Cloud Console. تتطلب واجهات برمجة التطبيقات وحزم تطوير البرامج (SDK) هذه استخدام رموز JSON المميّزة للويب تم توقيعها باستخدام حسابات خدمة تم إنشاؤها من Cloud Console.
إعداد مشروع على السحابة الإلكترونية
لإعداد مشروعك على السحابة الإلكترونية، عليك أولاً إنشاء مشروعك، ثم إنشاء حسابات الخدمة.
لإنشاء مشروعك على Google Cloud، اتّبِع الخطوات التالية:
- أنشِئ مشروعًا على Google Cloud باستخدام Google Cloud Console.
- باستخدام لوحة بيانات الخدمات وواجهات برمجة التطبيقات، مكِّن واجهة برمجة تطبيقات الرحلات المحلية والتسليمات
ترتبط حسابات الخدمة بدور واحد أو أكثر. تُستخدم لإنشاء رموز JSON المميّزة للويب التي تمنح مجموعات مختلفة من الأذونات استنادًا إلى الأدوار. وفي العادة، لتقليل احتمالية إساءة الاستخدام، يمكنك إنشاء أقسام متعددة حسابات الخدمة، لكل منها حد أدنى من مجموعة الأدوار المطلوبة.
يستخدم مستوى تقدّم الرحلة والطلبات الأدوار التالية:
الدور | الوصف |
---|---|
مستخدم حزمة SDK لمستهلك Fleet Engine
roles/fleetengine.consumerSdkUser |
يمنح الإذن بالبحث عن المركبات واسترداد المعلومات حول المركبات والرحلات. الرموز المميزة التي تم إنشاؤها من خلال حساب خدمة باستخدام هذا من الأجهزة الجوّالة لتطبيقات المستهلكين في خدمة مشاركة الرحلات أو التوصيل. |
مستخدم Fleet Engine Driver SDK
roles/fleetengine.driverSdkUser |
لمنح الإذن بتعديل المواقع الجغرافية للمركبات ومساراتها لاسترداد معلومات حول المركبات والرحلات. الرموز المميّزة التي تم إنشاؤها لحساب الخدمة الذي يتولى هذا الدور عادةً، يتم اختيار أو مشاركة الرحلات أو تطبيق سائق التوصيل على الأجهزة المحمولة. |
مشرف عند الطلب من Fleet Engine
roles/fleetengine.ondemandAdmin |
يمنح الإذن بالقراءة والكتابة لجميع موارد المركبات والرحلات. لا يحتاج المديرون الذين لديهم هذا الدور إلى استخدام JWT ويجب عليهم بدلاً من ذلك استخدام استخدام بيانات الاعتماد التلقائية للتطبيق. يتم تجاهل مطالبات JWT المخصّصة. ويجب أن يقتصر هذا الدور على البيئات الموثوق بها (الواجهة الخلفية للعميل). |
roles/fleetengine.serviceSuperUser |
يمنح الإذن لجميع واجهات برمجة تطبيقات المركبات والرحلات. تم إنشاء الرموز المميّزة
من خادم الخلفية، يتم استخدام هذا الدور عادةً من خلال حساب الخدمة.
الخوادم. تم إيقاف هذا الدور نهائيًا. تفضيل
roles/fleetengine.ondemandAdmin بدلاً من ذلك. |
على سبيل المثال، يمكنك إنشاء حساب خدمة لكل من الأدوار الثلاثة وتعيينها أدوارهم الخاصة.
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)'
).
مكتبة مصادقة Fleet Engine
يستخدم Fleet Engine رموز JSON المميّزة للويب (JWT) لحظر الوصول إلى واجهات برمجة تطبيقات Fleet Engine مكتبة مصادقة Fleet Engine الجديدة المتوفرة على GitHub، تبسيط إنشاء JWTs من Fleet Engine وتوقيعها بأمان.
توفر المكتبة الفوائد التالية:
- تبسيط عملية إنشاء الرموز المميّزة لـ Fleet Engine
- يتم توفير آليات توقيع الرمز المميز بخلاف استخدام ملفات بيانات الاعتماد (مثل انتحال هوية حساب خدمة).
- يرفق الرموز المميّزة الموقَّعة للطلبات الصادرة التي يتم إجراؤها من خلال كعب gRPC أو عميل GAPIC.
إنشاء رمز JSON المميّز للويب (JWT) للتفويض
في حال عدم استخدام مكتبة مصادقة Fleet Engine، يجب أن تكون رموز JSON Web Tokens (JWT) مباشرةً داخل قاعدة التعليمات البرمجية. وهذا يتطلب منك إجراء تحليل فهم JWT وكيفية ارتباطها بـ Fleet Engine. هذا هو السبب في أننا ننصح بشدة بالاستفادة من مكتبة مصادقة Fleet Engine.
داخل Fleet Engine، توفّر رموز JSON للويب (JWT) مصادقة قصيرة الأجل. والتأكّد من أنّ الأجهزة يمكنها تعديل المركبات أو الرحلات أو المهام فقط المخصص لهم. تحتوي ملفات JWT على عنوان وقسم مطالبة. يحتوي قسم العنوان على معلومات مثل المفتاح الخاص الذي سيتم استخدامه (يتم الحصول عليه من حسابات الخدمة) والتشفير للخوارزمية. يحتوي قسم المطالبة على معلومات مثل ووقت إنشاء الرمز المميز ومدة بقاء الرمز والخدمات وطلب الوصول إلى، ومعلومات التفويض الأخرى، لتحديد نطاق الوصول على سبيل المثال، رقم تعريف المركبة.
يحتوي قسم عنوان JWT على الحقول التالية:
الحقل | الوصف |
---|---|
طحالب | الخوارزمية المطلوب استخدامها. `RS256`. |
كتابة | تمثّل هذه السمة نوع الرمز المميّز. "JWT". |
طفلة | رقم تعريف المفتاح الخاص لحساب الخدمة. يمكنك العثور على هذه القيمة في الحقل "private_key_id" في ملف JSON لحساب الخدمة. تأكَّد من استخدام مفتاح من حساب خدمة يتضمّن مستوى الأذونات الصحيح. |
يحتوي قسم مطالبات JWT على الحقول التالية:
الحقل | الوصف |
---|---|
هوس | عنوان البريد الإلكتروني لحساب الخدمة. |
sub | عنوان البريد الإلكتروني لحساب الخدمة. |
Aud | SERVICE_NAME لحساب الخدمة الخاص بك، في هذه الحالة https://fleetengine.googleapis.com/ |
بروتوكول الإنترنت | الطابع الزمني الذي تم فيه إنشاء الرمز المميّز، والذي يتم تحديده بالثواني منذ 1 كانون الثاني (يناير) 1970، حتى الساعة 00:00:00 حسب التوقيت العالمي المنسَّق (UTC). اسمح لمدة 10 دقائق للحصول على انحراف. إذا كانت الطابع الزمني بعيد جدًا في الماضي، أو في المستقبل، قد يُبلغ الخادم عن خطأ. |
تجربة | الطابع الزمني لوقت انتهاء صلاحية الرمز المميّز، ويتم تحديده بالثواني منذ 1 كانون الثاني (يناير) 1970، حتى الساعة 00:00:00 حسب التوقيت العالمي المنسَّق (UTC). ويتعذّر إرسال الطلب إذا كان الطابع الزمني بعد أكثر من ساعة واحدة في المستقبل. |
authorization | حسب حالة الاستخدام، قد يحتوي على "vehicleid" أو "tripid". |
يشير إنشاء رمز JWT المميز إلى التوقيع عليه. للحصول على التعليمات وعينات التعليمات البرمجية لإنشاء JWT وتوقيعه، راجع تفويض حساب الخدمة بدون بروتوكول OAuth. يمكنك بعد ذلك إرفاق رمز مميّز موقَّع بمكالمات gRPC أو الطرق الأخرى المستخدَمة. للوصول إلى Fleet Engine.
مطالبات JWT
عند إنشاء حمولة JWT، أضِف مطالبة أخرى في التفويض
مع ضبط المفتاح vehicleid
أو tripid
على قيمة
معرّف المركبة أو معرّف الرحلة الذي يتم إجراء المكالمة له
تستخدم حزمة Driver SDK دائمًا المطالبة vehicleid
، سواء كانت تعمل على
برحلة أو مركبة. تؤكد الواجهة الخلفية لـ Fleet Engine أن المركبة
بالرحلة المطلوبة قبل إجراء التعديل.
دائمًا ما تستخدم حزمة تطوير البرامج (SDK) الخاصة بالمستهلك مطالبة واحدة (tripid
).
يجب أن يستخدم موفّرا خدمات مشاركة الرحلات أو التوصيل 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 على جهاز جوّال، احرص على استخدام حساب الخدمة لدور برنامج التشغيل أو حزمة تطوير البرامج (SDK) للمستهلك بخلاف ذلك، يحتوي الهاتف سيكون بإمكان جهازك تغيير الحالة التي يجب ألا تكون متوفّرة.
وبالمثل، عند توقيع JWT لاستخدامه في المكالمات المميزة، تأكَّد من لاستخدام حساب الخدمة الذي يمتلك دور "المستخدم المميّز" بخلاف ذلك، فإن صفحة ستفشل العملية.
إنشاء 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 حساب خدمة المستخدمين:
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
مقابل "المركبات المُدرَجة في القائمة".
نقطة نهاية REST:
curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"
المركبات ودورة حياتها
المركبة هي الكيان الذي يمثل زوجًا من مركبة السائق. حاليًا، لا يمكن تتبع السائق والمركبة بشكل منفصل. موفّر خدمة مشاركة الرحلات أو التوصيل تنشئ مركبة باستخدام رقم تعريف موفّر الخدمة (والذي يجب أن يكون مطابقًا لـ رقم تعريف المشروع الخاص بالمشروع على Google Cloud الذي يحتوي على حساب الخدمة يُستخدم لطلب واجهات برمجة تطبيقات Fleet Engine) ومعرّف المركبة التي يملكها موفّر خدمات مشاركة الرحلات أو خدمة التوصيل.
بالنسبة إلى مركبة لم يتم تحديثها عبر UpdateVehicle
بعد سبعة أيام
تلقائيًا، ويتمّ وضع علامة على الرحلات المخصّصة لها، إن توفّرت،
غير معين. النهج الموصى به للحفاظ على مركبة متوفرة
في Fleet Engine هو تحديث موقعه على فترات منتظمة. التحديثات على معظم التحديثات
الحقول الأخرى في الكيان Vehicle
، سيتم إطالة عمرها أيضًا، بشرط أن
تختلف قيمة الحقل الجديد عن القيمة الحالية.
ملاحظة: بعض الحقول في الكيان Vehicle
، مثل device_settings
، هي للتصحيح البحتة
المعلومات التي لا يحتفظ بها Fleet Engine. لا يؤدي تحديثها إلى
إطالة عمر الكيان Vehicle
.
حدث خطأ عند الاتصال بـ CreateVehicle
باستخدام
زوج رقم تعريف الموفّر/رقم تعريف المركبة موجودان من قبل. حالة المركبات التي
لا يتم تحديثها بشكل متكرر بطريقتين: الاتصال المتكرر
CreateVehicle
يتضمن زوجًا متوقعًا من رقم تعريف المركبة/رقم تعريف المركبة، ويتم تجاهله
ظهور الخطأ إذا كانت المركبة متوفّرة مسبقًا أو الاتصال بـ CreateVehicle
بعد
يتم إرجاع UpdateVehicle
مع ظهور خطأ NOT_FOUND
.
إشعارات بشأن الموقع الجغرافي للمركبة
للحصول على أفضل أداء باستخدام Fleet Engine، ننصحك بتوفير مجموعة من المركبات. تحديثات الموقع الجغرافي. استخدِم إحدى الطريقتَين التاليتَين لتقديم هذه التعديلات:
- استخدام حزمة تطوير البرامج (SDK) لبرنامج التشغيل - Android، iOS - أبسط الخيارات.
- استخدام رمز مخصّص، وهو مفيد إذا كانت المواقع الجغرافية عبر الخلفية، أو إذا كنت تستخدم أجهزة بخلاف Android أو iOS.
أنواع المركبات
يتضمّن كيان المركبة الحقل المطلوب VehicleType
، الذي يحتوي على
تعداد Category
يمكن تحديده على النحو التالي: AUTO
أو TAXI
أو TRUCK
TWO_WHEELER
أو BICYCLE
أو PEDESTRIAN
. يمكن أن يكون نوع المركبة بمثابة
معايير الفلتر في SearchVehicles
وListVehicles
ستستخدم جميع مسارات التوجيه للمركبات RouteTravelMode
المقابل إذا كانت
تم ضبط الفئة على AUTO
أو TWO_WHEELER
أو BICYCLE
أو PEDESTRIAN
.
إذا تم ضبط الفئة على TAXI
أو TRUCK
، يتم التعامل مع التوجيه بالطريقة نفسها المتّبعة
وضع AUTO
.
سمات المركبات
تتضمّن كيان المركبة حقلاً متكرّرًا للسمة VehicleAttribute
. هذه
التي لا يتم تفسيرها بواسطة Fleet Engine. SearchVehicles
تتضمّن واجهة برمجة التطبيقات حقلاً يتطلّب أن يحتوي Vehicles
المطابِق على جميع
تعيين السمات المضمنة إلى القيمة المحددة.
يُرجى العلم أنّ حقل السمة بالإضافة إلى عدة حقول أخرى متوافقة
في رسالة Vehicle
، مثل vehicle_type
وsupported_trip_types
.
نقاط الطريق المتبقية للمركبة
تحتوي كيان المركبة على حقل متكرّر للسمة TripWaypoint
(RPC | REST)،
باسم waypoints
(RPC | REST).
يتضمن هذا الحقل نقاط الطريق المتبقية في الرحلات، بالترتيب الذي
وصول المركبة إليهم. يحسب Fleet Engine هذا الحقل لأن الرحلات
المخصصة للمركبة وتحديثها عند تغيير حالتها.
يمكن تحديد نقاط الطريق هذه من خلال الحقل TripId
والحقل WaypointType
.
زيادة أهلية المركبات للمشاركة في المباريات
في العادة، تكون خدمات مشاركة الرحلات أو مقدّم خدمة التوصيل مسؤولة عن مطابقة الرحلة
الطلبات إلى المركبات. يمكن أن تستخدم الخدمة سمات المركبة لتضمين
مركبة في عدد أكبر من عمليات البحث. على سبيل المثال، يمكن للمزود تنفيذ
مجموعة إلى السمات المقابلة لمستويات المزايا أو الإمكانات التي يقدمها
مركبة. على سبيل المثال، يمكن أن تكون ثلاثة مستويات عبارة عن مجموعة من السمات ذات القيم المنطقية
القيم: is_bronze_level
وis_silver_level
وis_gold_level
. مركبة
مؤهلاً لجميع الأطراف الثلاثة. عندما يتلقى Fleet Engine طلبًا
رحلة تتطلب إمكانات المستوى الفضي، فإن البحث يتضمن تلك المركبة.
واستخدام السمات بهذه الطريقة يشمل المركبات التي تقدّم مجموعة متنوعة من
والإمكانات.
تتوفّر طريقتان لتعديل سمات المركبة: وَاحِدْ هُوَّ UpdateVehicle
واجهة برمجة التطبيقات. عند استخدام واجهة برمجة التطبيقات هذه، تصبح مجموعة "سمات المركبة" بالكامل
تعيينها على القيمة. لا يمكن تعديل سمة واحدة فقط.
أما الطريقة الأخرى، فهي UpdateVehicleAttributes
API. تستغرق هذه الطريقة فقط
السمات التي سيتم تحديثها. وستكون السمات التي يتضمنها الطلب هي
عند ضبطها على القيمة الجديدة أو المضافة، التي لن يتم تغيير السمات غير المحددة لها.
طريقة التنفيذ: إنشاء مركبة
يجب إنشاء كيان "Vehicle
" لكل مركبة ليتم تتبّعها في الأسطول.
استخدِم نقطة نهاية CreateVehicle
مع CreateVehicleRequest
لإنشاء
المركبة.
يجب أن يكون provider_id
من Vehicle
هو رقم تعريف المشروع.
(مثل مشروعي عند الطلب) ضمن مشروع Google Cloud الذي يتضمّن
حسابات الخدمة التي سيتم استخدامها لطلب Fleet Engine لاحظ أنه في حين أن
يمكن لحسابات خدمة متعددة الوصول إلى Fleet Engine لاستخدام ميزة "مشاركة الرحلة" نفسها.
أو مزود التسليم، لا يدعم Fleet Engine حسابات الخدمة من
عدة مشاريع على Google Cloud يمكنها الوصول إلى Vehicles
نفسه.
يمكن إنشاء Vehicle
بالحالة OFFLINE
أو ONLINE
. في حال حذف
تم إنشاؤه ONLINE
، وقد يتم إرجاعه فورًا استجابةً للطلب SearchVehicles
طلبات البحث.
قد يتم تضمين last_location
مبدئي في مكالمة CreateVehicle
.
على الرغم من السماح بذلك، لا يجب إنشاء Vehicle
في الحالة ONLINE
بدون
last_location
.
يمكنك الاطّلاع على أنواع المركبات للحصول على تفاصيل عن المركبة. النوع.
راجِع سمات المركبة لمعرفة التفاصيل. في حقل السمات.
القيمة التي يعرضها CreateVehicle
هي كيان Vehicle
الذي تم إنشاؤه.
مثال
shell
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 المرجع.
Java
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 لإنشاء المركبات
تكتب واجهة برمجة تطبيقات Fleet Engine إدخال سجل عبر سجلات Google Cloud Platform عندما
تلقي مكالمة لنقطة النهاية CreateVehicle
. يتضمن إدخال السجل
معلومات عن القيم في طلب CreateVehicle
. إذا كانت المكالمة
، فسيتضمن أيضًا معلومات عن Vehicle
التي كانت
عاد.
shell
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 إشعارًا عبر Cloud Pub/Sub عند توفر إنشاء مركبة. لتلقّي هذه الإشعارات، يُرجى اتّباع التعليمات هنا.
طريقة التنفيذ: تعديل الموقع الجغرافي للمركبة
إذا لم تكن تستخدم "حزمة تطوير البرامج (SDK) للسائق" لتعديل الموقع الجغرافي للمركبة، يمكنك إنشاء مباشرة إلى Fleet Engine مع موقع المركبة. لأي مركبة نشطة يتوقع Fleet Engine تحديث الموقع مرة واحدة على الأقل كل دقيقة مرة كل 5 ثوانٍ. لا تتطلّب هذه التحديثات سوى مستخدم Fleet Engine Driver SDK. الامتيازات.
مثال
shell
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 المرجع.
Java
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
يشتمل UpdateVehicleRequest
على update_mask
للإشارة إلى الحقول التي يجب
تحديث. كما أن سلوك الحقل هو كما هو الحال في وثائق Protobuf
أقنعة الحقل.
كما هو موضّح في سمات المركبة، يؤدي تعديل
يتطلب الحقل attributes
كتابة جميع السمات المراد الاحتفاظ بها. أُنشأها جون هنتر، الذي كان متخصصًا
لا يمكن تحديث قيمة زوج واحد من المفتاح/القيمة فقط في
مكالمة واحدة (UpdateVehicle
) لتعديل قيم سمات محددة، يجب إدخال
يمكن استخدام واجهة برمجة تطبيقات UpdateVehicleAttributes
.
مثال
يتيح هذا المثال تفعيل السمة back_to_back
.
shell
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 المرجع.
Java
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 لتحديثات المركبات
تكتب واجهة برمجة تطبيقات Fleet Engine إدخال سجل عبر سجلات Google Cloud Platform عندما
تلقي مكالمة لنقطة النهاية UpdateVehicle
. يتضمن إدخال السجل
معلومات عن القيم في طلب UpdateVehicle
. إذا كانت المكالمة
، فسيتضمن أيضًا معلومات عن Vehicle
التي كانت
عاد.
shell
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 إشعارًا عبر Cloud Pub/Sub عند وجود تم تحديث المركبة. لتلقّي هذه الإشعارات، يُرجى اتّباع التعليمات هنا.
طريقة التنفيذ: البحث عن مركبات
يدعم Fleet Engine البحث عن المركبات. SearchVehicles
تتيح لك واجهة برمجة التطبيقات العثور على السائقين القريبين الذين هم الأكثر ملاءمة لمهمة مثل
عن خدمة رحلة أو طلب توصيل. تعرض واجهة برمجة التطبيقات SearchVehicles
قائمة السائقين الذين يطابقون سمات المهام مع سمات المركبات في
أسطولك. لمزيد من المعلومات، يُرجى مراجعة
العثور على السائقين القريبين
مثال
عند البحث عن مركبات متاحة، يستبعد Fleet Engine المركبات على الرحلات النشطة بشكل افتراضي. يجب أن تفي خدمات "مشاركة الرحلة" أو "مقدِّم خدمات التوصيل" بما يلي: تضمينها بشكل صريح في طلبات البحث. يوضح المثال التالي كيفية تضمين تلك المركبات في عملية البحث عن مركبات تتطابق مع رحلة من إندونيسيا إيست مول ومركز بالاي سيدانغ جاكرتا للمؤتمرات.
shell
قم أولاً بتحديث موقع المركبة الذي أنشأناه في الخطوات السابقة بحيث مؤهَّل. في الواقع، يتم تنفيذ ذلك من خلال حزمة تطوير البرامج (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
عرض providers.vehicles.search المرجع.
Java
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
العثور على جميع المركبات التي تستوفي بعض معايير معيّنة.
خيارات الطلب. تعرض واجهة برمجة التطبيقات ListVehicles
قائمة مركبات مقسّمة على صفحات في
المشروع الذي يلبي بعض المتطلبات.
لفلترة سمات المركبات، يُرجى الرجوع إلى طلب بحث فلترة المركبات:
مثال
يجري هذا المثال الفلترة على vehicle_type
والسمات باستخدام
سلسلة filter
shell
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 المرجع.
Java
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;
}
الرحلات ومراحل نشاطها
تشابه واجهة برمجة تطبيقات الرحلة ورحلة النشاط مع واجهة برمجة تطبيقات المركبات ومراحل النشاط.
"مقدِّم خدمة مشاركة الرحلات" مسؤول عن إنشاء الرحلات باستخدام Fleet Engine.
من الواجهات. يوفر Fleet Engine خدمة RPC
TripService
، وREST، provider.trips
. تتيح هذه الواجهات إنشاء عناصر الرحلة، وطلبات المعلومات، والبحث
ووظائفه وإمكانية التحديث.
يحتوي Trip
على حقل حالة لتتبُّع مستوى التقدّم خلال مراحل النشاط.
تنتقل القيم من NEW
إلى COMPLETE
بالإضافة إلى CANCELED
وUNKNOWN_TRIP_STATUS
. يُرجى الرجوع إلى trip_status
للاطّلاع على استدعاء الإجراءات عن بُعد.
أو TripStatus for 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
ضمن كيان المركبة وSearchTripsRequest
.
لا يمكن لخدمتك تغيير vehicle_id
الذي تم تخصيصه لرحلة إلا عند الرحلة.
نشطة. على سبيل المثال، ستفعل ذلك عندما يلغي أحد السائق رحلة بينما
ذلك، ويُعاد تعيين الرحلة إلى مركبة أخرى.
تُعد الحالة مهمة عند تنفيذ البيانات المتتالية دعم الرحلات يتيح هذا الدعم لمقدّم الخدمة تخصيص رحلة جديدة إلى مركبة معيّنة. عندما تكون تلك المركبة في رحلة نشطة الرمز لإنشاء "رحلة" انتقالية، فهي مماثلة للرحلة الفردية وتستخدم نفس معرّف المركبة. يضيف Fleet Engine منشأ ووجهة الرحلة الجديدة إلى نقاط الطرق للمركبة. للحصول على مزيد من المعلومات حول الرحلات المتتالية، يمكنك الاطّلاع على إنشاء رحلات متعددة النقاط:
نقاط الطريق المتبقية للرحلة
يحتوي كيان الرحلة على حقل متكرّر من TripWaypoint
(RPC | REST)،
يُسمى remainingWaypoints
(RPC | REST).
يتضمّن هذا الحقل جميع نقاط الطريق التي يجب أن تقطعها المركبة بالترتيب
قبل نقطة التسليم الأخيرة لهذه الرحلة. فهو يحسب من
نقاط المسار المتبقية للمركبة:
في حالات الاستخدام المتتالية ومشاركة رحلة السيارة، تحتوي هذه القائمة على نقاط طريق من
الرحلات الأخرى التي سيتم اجتيازها قبل هذه الرحلة، باستثناء أي نقاط مسار
بعد هذه الرحلة. يمكن تحديد النقطة الوسيطة في القائمة من خلال TripId
.
وWaypointType
.
العلاقة بين حالة الرحلة ونقاط الطريق المتبقية للمركبة
ستتم تنفيذ نقاط الطريق المتبقية للمركبة (RPC | REST)
عندما يتلقى Fleet Engine طلبًا بتغيير حالة الرحلة. تشير رسالة الأشكال البيانية
ستتم إزالة النقطة الوسيطة السابقة من قائمة نقاط الطريق المتبقية للمركبة عندما
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
- سلسلة أنشأها "مقدِّم خدمة مشاركة الرحلات".trip
- حاوية تتضمّن بيانات وصفية أساسية تصف الرحلةtrip_type
- تعداد يمثّل ما إذا كانت الرحلة قد تتضمن مسافرين آخرين من مصدر ووجهة مختلفَين في المركبة نفسها (SHARED
) أو طرف واحد فقط (EXCLUSIVE
).pickup_point
- TerminalLocation الذي يمثل نقطة انطلاق تخييم. راجِع مرجع استدعاء إجراء عن بُعد (RPC). أو مرجع RST
عند إنشاء رحلة، يمكنك توفير number_of_passengers
وdropoff_point
.
وvehicle_id
. على الرغم من أنّ هذه الحقول غير مطلوبة، في حال توفيرها:
الاحتفاظ بها. ويتم تجاهل جميع حقول "الرحلة" الأخرى. على سبيل المثال، كلّ الرحلات
يبدأ بـ trip_status
من NEW
حتى إذا نجحت في اجتياز trip_status
من
CANCELED
في طلب الإنشاء
مثال
ينشئ المثال التالي رحلة إلى جراند إندونيسيا إيست مول. الرحلة
وهي مخصصة لراكبَين وهي حصرية. يجب أن يكون provider_id
من Trip
هو نفس رقم تعريف المشروع. في المثال، أنشأ موفر خدمة مشاركة الرحلات
مشروع Google Cloud، project-id. ينبغي أن يحتوي هذا المشروع على
حسابات الخدمة المستخدمة لاستدعاء Fleet Engine. حالة الرحلة هي "NEW
".
وفي وقت لاحق، بعد أن تطابق الخدمة الرحلة إلى مركبة، يمكن للخدمة الاتصال
UpdateTrip
وتغيير vehicle_id
عند تحديد الرحلة لمركبة.
shell
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 المرجع.
Java
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 لإنشاء الرحلات
تكتب واجهة برمجة تطبيقات Fleet Engine إدخال سجل باستخدام سجلات Google Cloud Platform عندما
تلقي مكالمة لنقطة النهاية CreateTrip
. يتضمن إدخال السجل
معلومات عن القيم في طلب CreateTrip
. إذا كانت المكالمة
، فسيتضمن أيضًا معلومات حول Trip
التي تم إرجاعها.
طريقة التنفيذ: تعديل رحلة
يحتوي كيان "الرحلة" على حقول تمكّن التتبّع حسب الخدمة ولـ
إعداد تقارير عن تقدُّم الرحلة من خلال حزمة تطوير البرامج (SDK) لبرنامج التشغيل
حزمة SDK للمستهلكين لتعديل السمات، استخدِم UpdateTripRequest
.
. يؤدي ذلك إلى تعديل حقول "الرحلة" وفقًا لـ field_mask
في الطلب.
راجِع UpdateTripRequest.
"مقدِّم خدمة مشاركة الرحلات" مسؤول عن تعديل السمات التالية:
- حالة الرحلة.
- رقم تعريف المركبة إمّا في وقت الإنشاء، أو بعد مطابقة المركبة تخييم.
- التغييرات في استلام الطلب أو التسليم أو نقاط الطريق
يقوم Fleet Engine تلقائيًا بتحديث الحقول التالية عند استخدام ميزة "المشاركة في الرحلة" من خلال Driver SDK أو حزمة تطوير البرامج (SDK) الخاصة بالمستهلك:
- المسارات
- الوقت المُقدّر للوصول
- المسافة المتبقية
- الموقع الجغرافي للمركبة
- نقاط الطريق المتبقية
راجِع القسم Trip
في استدعاء إجراء عن بُعد أو
Resource.Trip
في REST.
سجلّات Google Cloud Platform للاطّلاع على "آخر الأخبار"
تكتب واجهة برمجة تطبيقات Fleet Engine إدخال سجل باستخدام سجلات Google Cloud Platform عندما
تلقي مكالمة لنقطة النهاية UpdateTrip
. يتضمن إدخال السجل
معلومات عن القيم في طلب UpdateTrip
. إذا نجحت المكالمة،
ستتضمّن أيضًا معلومات حول Trip
التي تم إرجاعها.
طريقة التنفيذ: البحث عن الرحلات
يدعم Fleet Engine البحث عن الرحلات. كما أشرنا سلفًا، تعتبر الرحلة
يتم حذفها تلقائيًا بعد سبعة أيام، لذا لن تسمح لـ SearchTrips
عرض سجل كامل لجميع الرحلات.
على الرغم من أنّ SearchTrips
هي واجهة برمجة تطبيقات مرنة، تراعي القائمة أدناه حالتَي استخدام.
تحديد الرحلات النشطة للمركبة: يمكن لموفّر المحتوى تحديد رحلات مركبة نشطة حاليًا. داخل
SearchTripsRequest
، تم ضبطvehicle_id
على المركبة التي يتم النظر فيها وactive_trips_only
. يجب ضبطها علىtrue
.التوفيق بين موفّر الخدمة وحالة محرك الأسطول -- يمكن لموفّر الخدمة استخدام
SearchTrips
للتأكّد من تطابق حالة الرحلة مع حالة Fleet Engine. وهذا مهم بشكل خاص لحالة TripStatus. إذا كانت حالة الرحلة معيّنة إلى مركبة غير مضبوطة بشكل صحيح علىCOMPLETE
أوCANCELED
، المركبة لم يتم تضمينها فيSearchVehicles
.
لاستخدام SearchTrips
بهذه الطريقة، اترك vehicle_id
فارغًا، واضبط القيمة active_trips_only
.
على true
، وضبط minimum_staleness
على وقت أكبر من معظم مُدد الرحلات.
على سبيل المثال، يمكنك استخدام ساعة واحدة. تتضمن النتائج رحلات غير
COMPLETE أو CancelED، ولم يتم إجراء أي تعديل خلال أكثر من ساعة مزوِّد الخدمة
فحص هذه الرحلات للتأكد من أن حالتها في Fleet Engine
بشكل صحيح.
تحديد المشاكل وحلّها
في حال حدوث خطأ DEADLINE_EXCEEDED
، تكون حالة Fleet Engine هي:
غير معروف. على موفّر الخدمة الاتصال بـ CreateTrip
مرة أخرى، وسيؤدي ذلك إما إلى عرض
201 (CREATED) أو 409 (CONFLICT). نجح الطلب السابق في الحالة الثانية
قبل DEADLINE_EXCEEDED
. الاطّلاع على أدلة Consumer API للحصول على مزيد من المعلومات
حول التعامل مع أخطاء الرحلة: Android
أو iOS.
دعم بشأن رحلات مشاركة السيارة
يمكنك تحديد رحلات "SHARED
" متعددة إلى مركبة تتيح استخدام "TripType.SHARED
".
يلزمك تحديد ترتيب جميع نقاط الطريق غير التي تم تجاوزها لجميع الرحلات المحددة إلى
المركبة في هذه الرحلة المشتركة عبر Trip.vehicle_waypoints
عند تعيين
vehicle_id
لرحلة مشتركة (في طلب CreateTrip
أو UpdateTrip
)
يُرجى الرجوع إلى vehicle_waypoints
للاطّلاع على استدعاء الإجراءات عن بُعد.
أو vehicleWaypoints
لـ REST.
توفّر الوجهات المتعددة
تحديد وجهة وسيطة
الحقل intermediateDestinations
والحقل intermediateDestinationIndex
في رحلة (RPC | REST)
يمكن دمجها للإشارة إلى الوجهة.
تعديل الوجهة المتوسطة
ويمكنك تعديل الوجهات المتوسطة من خلال UpdateTrip
. عند التحديث
وجهات متوسطة، يجب عليك تقديم قائمة كاملة بالوجهات المتوسطة
بما في ذلك الأشخاص الذين سبق لهم زيارة المكان، وليست تلك التي تمت زيارتها حديثًا
إضافتها أو تعديلها.
عندما تشير intermediateDestinationIndex
إلى فهرس بعد موضع
الوجهة المتوسطة التي تمت إضافتها أو تعديلها حديثًا، والوسيط الجديد/المحدّث
لن تتم إضافة الوجهة إلى waypoints
للمركبة أو remainingWaypoints
للرحلة.
السبب هو أنّ أيّ وجهات وسيطة قبل intermediateDestinationIndex
على أنه تمت زيارته من قبل.
التغييرات على حالة الرحلة
الحقل intermediateDestinationsVersion
في (RPC | REST)
مطلوبة في طلب تعديل حالة الرحلة الذي يتم إرساله إلى Fleet Engine للإشارة إلى
انقضت وجهة وسيطة. الوجهة المتوسطة المستهدفة
يتم تحديدها من خلال الحقل intermediateDestinationIndex
.
عندما تكون قيمة tripStatus
(RPC | REST) هي ENROUTE_TO_INTERMEDIATE_Destination، رقم بين
[0..N-1] تشير إلى الوجهة الوسيطة التي ستعبرها المركبة بعد ذلك.
عندما يكون tripStatus
هو ARRIVED_AT_INTERMEDIATE_{9/}، يكون الرقم بين
[0..N-1] تشير إلى الوجهة الوسيطة التي تصل إليها المركبة.
مثال
يوضح مثال الرمز التالي كيفية تحديث حالة رحلة إلى المسار إلى أول وجهة متوسطة لها، على افتراض أنك أنشأت متعددة الوجهات وتجاوزت الرحلة نقطة الركوب.
Java
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;
}
طريقة التنفيذ: الاشتراك في رسائل الإشعارات من Fleet Engine API
تستخدم واجهة برمجة تطبيقات Fleet Engine خدمة Google Cloud Pub/Sub. لنشر إشعارات حول الموضوع الذي أنشأه المستهلك على Google Cloud المشروع. لا يتم تفعيل ميزة "النشر/الاشتراك" تلقائيًا في Fleet Engine على Google Cloud. مشروعك. يُرجى تقديم حالة دعم أو التواصل مع مهندس العملاء لتفعيل ميزة النشر/الاشتراك.
لإنشاء موضوع في مشروع Cloud، اتّبِع هذه التعليمات. يجب أن يكون رقم تعريف الموضوع هو "fleet_engine_notifications".
يجب إنشاء الموضوع في المشروع نفسه على السحابة الإلكترونية الذي يطلب تشغيل Fleet Engine. واجهات برمجة التطبيقات.
بعد إنشاء الموضوع، ستحتاج إلى منح Fleet Engine API
إذنًا لنشر معلومات حول الموضوع لإجراء ذلك، انقر على الموضوع الذي تريد
قمت بإنشائه للتو وإضافة إذن جديد. قد تحتاج إلى النقر على عرض لوحة المعلومات لفتح محرِّر الأذونات.
يجب أن يكون الحساب الرئيسي geo-fleet-engine@system.gserviceaccount.com
.
ويجب أن يكون الدور Pub/Sub publisher
.
لإعداد مشروع Cloud للاشتراك في الإشعارات، اتّبِع هذه التعليمات.
ستنشر واجهة برمجة تطبيقات Fleet Engine كل إشعار في بياناتين مختلفين
التنسيقات، 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"
}
}
}