بدء استخدام Fleet Engine

تتيح لك واجهة برمجة تطبيقات الرحلات عند الطلب عند الطلب من 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، اتّبِع الخطوات التالية:

  1. أنشِئ مشروعًا على Google Cloud باستخدام Google Cloud Console.
  2. باستخدام لوحة بيانات الخدمات وواجهات برمجة التطبيقات، مكِّن واجهة برمجة تطبيقات الرحلات المحلية والتسليمات

ترتبط حسابات الخدمة بدور واحد أو أكثر. تُستخدم لإنشاء رموز JSON المميّزة للويب التي تمنح مجموعات مختلفة من الأذونات استنادًا إلى الأدوار. وفي العادة، لتقليل احتمالية إساءة الاستخدام، يمكنك إنشاء أقسام متعددة حسابات الخدمة، لكل منها حد أدنى من مجموعة الأدوار المطلوبة.

يستخدم مستوى تقدّم الرحلة والطلبات الأدوار التالية:

الدورالوصف
مستخدم حزمة SDK لمستهلك Fleet Engine

roles/fleetengine.consumerSdkUser		 يمنح الإذن بالبحث عن المركبات واسترداد المعلومات حول المركبات والرحلات. الرموز المميزة التي تم إنشاؤها من خلال حساب خدمة باستخدام هذا من الأجهزة الجوّالة لتطبيقات المستهلكين في خدمة مشاركة الرحلات أو التوصيل.
مستخدم Fleet Engine Driver SDK

roles/fleetengine.driverSdkUser		 لمنح الإذن بتعديل المواقع الجغرافية للمركبات ومساراتها لاسترداد معلومات حول المركبات والرحلات. الرموز المميّزة التي تم إنشاؤها لحساب الخدمة الذي يتولى هذا الدور عادةً، يتم اختيار أو مشاركة الرحلات أو تطبيق سائق التوصيل على الأجهزة المحمولة.
مشرف عند الطلب من Fleet Engine

roles/fleetengine.ondemandAdmin		 يمنح الإذن بالقراءة والكتابة لجميع موارد المركبات والرحلات. لا يحتاج المديرون الذين لديهم هذا الدور إلى استخدام JWT ويجب عليهم بدلاً من ذلك استخدام استخدام بيانات الاعتماد التلقائية للتطبيق. يتم تجاهل مطالبات JWT المخصّصة. ويجب أن يقتصر هذا الدور على البيئات الموثوق بها (الواجهة الخلفية للعميل).
المستخدم المتميّز في خدمة FleetEngine **(متوقف)**

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، ننصحك بتوفير مجموعة من المركبات. تحديثات الموقع الجغرافي. استخدِم إحدى الطريقتَين التاليتَين لتقديم هذه التعديلات:

  1. استخدام حزمة تطوير البرامج (SDK) لبرنامج التشغيل - Android، iOS - أبسط الخيارات.
  2. استخدام رمز مخصّص، وهو مفيد إذا كانت المواقع الجغرافية عبر الخلفية، أو إذا كنت تستخدم أجهزة بخلاف 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"
    }
  }
}