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

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

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

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

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

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

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

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

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

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

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

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

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

يمكنك تعديل سمات المركبة باستخدام 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

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