تعديل حقول المركبات

يتناول هذا المستند حقول المركبات المهمة التي يمكنك تعديلها عند إنشاء المركبات وإدارتها.

  • vehicle_state: لتحديد مدى توفّر المركبة للرحلات الجديدة.
  • ‫vehicle_type: حقل مطلوب عند إنشاء مركبة. يمكن أن يعمل الحقل أيضًا كمعايير فلترة لمطابقات المركبات. اطّلِع على مقالة إنشاء مركبة للاطّلاع على تفاصيل حول ضبط هذا الحقل.
  • attributes[]: مصفوفة اختيارية من النوع VehicleAttribute. استخدِم هذه المعايير لتحديد معايير مخصّصة لتحسين السلوك الفلتري عند البحث عن المركبات أو عرضها.
  

للحصول على قائمة كاملة بحقول المركبات، يُرجى الاطّلاع على:

حقل حالة المركبة

يمكن للنظام ضبط حالة المركبة على OFFLINE أو ONLINE. على سبيل المثال، يمكنك ضبط حالة المركبة على ONLINE كل يوم في الساعة 9 صباحًا وOFFLINE كل يوم في الساعة 5 مساءً.

وضع "بلا إنترنت" وضع "الاتصال بالإنترنت"
استخدِم OFFLINE للإشارة إلى أنّ المركبة لا تقبل الرحلات الجديدة. يُرجى العِلم أنّه لا يزال بإمكان المركبة إكمال الرحلات المخصّصة لها وهي في هذه الحالة.
  • قد يتم عرض Vehicle تم إنشاؤه في الحالة ONLINE على الفور في استجابةً لطلبات بحث SearchVehicles. اطّلِع على البحث عن المركبات للحصول على مزيد من التفاصيل.
  • يجب أن تستخدم المركبات التي تم إنشاؤها في ولاية ONLINE الحقل last_location في طلب CreateVehicle.

حقل سمات المركبة

استخدِم حقل المركبة attributes لإنشاء معايير مخصّصة تتيح للمستهلكين أو مشغّلي الأسطول العثور على المركبات في أسطولك من خلال مجموعة متنوعة من معايير البحث. ويؤدي ذلك إلى تحسين إمكانات تطبيقاتك لتوفير مطابقات أفضل للمركبات مقارنةً بما يمكنك الحصول عليه من خلال استخدام معايير البحث استنادًا إلى حقول المركبات الأخرى فقط. يمكن أن تحتوي كل مركبة على 100 سمة كحد أقصى، ويجب أن يكون لكل منها مفتاح فريد. يمكن أن تكون القيم سلاسل أو قيمًا منطقية أو أرقامًا.

على سبيل المثال، يمكنك تحديد سمة مخصّصة باسم class لتمييز المركبات المشاركة في خدمة النقل العام على مستوى الفئات. يمكنك استخدام ملفوظات السلسلة التالية لتمثيل مستويات فئة المركبات: ECONOMY وSTANDARD وLUXURY.

ومع ذلك، ليس من الضروري أن تكون قيم السمات المخصّصة متعارضة مع بعضها. يمكنك استخدام معايير مثل يسمح باصطحاب الحيوانات الأليفة ويمنع التدخين ويمكنه إجراء رحلات أطول. يمكن أن يكون كلٌّ من هذه السمات سمة مخصّصة منفصلة تستخدِم قيمًا منطقية. يمكن تخصيص كلّ من هذه السمات المخصّصة الثلاث لمركبة معيّنة، بالإضافة إلى السمة المخصّصة class التي تم ضبطها على قيمة السلسلة المناسبة.

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

تعديل سمات المركبات

يمكنك تعديل سمات المركبة باستخدام UpdateVehicle أو UpdateVehicleAttributes. ويمكن أن يحتوي كل مفتاح attributes على قيمة واحدة فقط لكل مركبة. يمكنك الإفصاح عن سمات المركبات المخصّصة باستخدام attributes في قناع الحقل، ثم تقديم القيم استنادًا إلى الطريقة الموضّحة أدناه.

UpdateVehicle UpdateVehicleAttributes
لا تسمح واجهة برمجة التطبيقات هذه بتعديل سمة واحدة فقط. عند استخدام هذه الطريقة، يؤدي أي استخدام لحقل attributes في قناع الحقل إلى إعادة تعريف المجموعة الكاملة لسمات المركبة. ويؤدي ذلك إلى استبدال أي سمة حالية لم يتم تضمينها صراحةً في قناع الحقل. إذا كنت تستخدِم هذه الطريقة لتعريف سمة مخصّصة جديدة، يجب أيضًا إعادة تعريف كل سمة مخصّصة تريد أن تحتفظ بها المركبة. في حال استبعاد attributes في قناع الحقل، تترك هذه الطريقة السمات المخصّصة الحالية كما تم تحديدها سابقًا للمركبة. في حال استخدام attributes في قناع الحقل، ولكن بدون ضبط القيم، يعادل ذلك إزالة جميع السمات المخصّصة من المركبة. تقبل هذه الطريقة قائمة محدّدة من السمات التي تريد تعديلها. لا يعدّل الطلب أو يضيف سوى السمات المحدّدة في قناع الحقل. وتبقى السمات المتوفّرة مسبقًا والتي لم يتم تحديدها بدون تغيير.

مثال على تعديل حقول المركبات

يعرض هذا القسم كيفية تعديل حقول المركبات باستخدام UpdateVehicleRequest، التي تتضمّن update_mask للإشارة إلى الحقول التي يجب تعديلها. اطّلِع على مستندات Protocol Buffers حول أقنعة الحقول للحصول على التفاصيل.

تتطلّب تعديلات الحقول غير last_location امتيازات Fleet Engine On-demand المشرف.

مثال: تفعيل نوع رحلة وسمة مخصّصة جديدَين

يتيح هذا المثال back_to_back رحلة للمركبة ويحدّد أيضًا سمة جديدة: class. كما هو موضّح في مقالة تعديل سمات المركبات سابقًا، يتطلّب تعديل الحقل attributes باستخدام هذا النهج الإشارة إلى كل السمات المخصّصة التي تريد الاحتفاظ بها. لذلك، يعرض المثال قيمة cash_only مكتوبة للحفاظ عليها من الكتابة فوقها أثناء عملية تعديل تحدّد حقل attributes.

لتعديل قيمة زوج سمة مفتاح/قيمة واحد فقط، استخدِم الأسلوب UpdateVehicleAttributes بدلاً من ذلك ولا تُدرِج حقل attribute في قناع الحقل لطلب UpdateVehicle.

اطّلِع على مرجع providers.vehicles.update لمزيد من المعلومات عن gRPC وREST.

gRPC

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("class").setValue("ECONOMY").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();

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.

REST

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": "class", "value": "LUXURY"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

الخطوات التالية