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

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

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

على سبيل المثال، يمكنك تحديد سمة مخصّصة باسم zone لتمييز المنطقة التي تعمل فيها مركبات التسليم في المدينة. يمكنك استخدام قيم سلاسل مثل ما يلي لتمثيل مناطق مختلفة: 1B و2C و3A. يمكنك بعد ذلك استخدام فلتر في ميزة "تتبُّع الأسطول" لعرض المركبات التي تعمل في منطقة معيّنة فقط للمشغّل المسؤول عن تلك المنطقة.

ومع ذلك، لا يجب أن تكون قيم السمات المخصّصة متعارضة مع بعضها. يمكنك استخدام معايير مثل available-at-night وhas-refrigeration. يمكن أن يكون كلّ من هذين العنصرين سمة مخصّصة منفصلة تستخدِم قيمًا منطقية. يمكن تحديد كلّ من السمات المخصّصة الثلاث هذه بالإضافة إلى السمة المخصّصة zone لمركبة معيّنة مع ضبط قيمتها على السلسلة المناسبة.

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

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

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

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

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

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

  static final String PROJECT_ID = "my-delivery-co-gcp-project";
  static final String VEHICLE_ID = "vehicle-8241890";

  DeliveryServiceBlockingStub deliveryService =
    DeliveryServiceGrpc.newBlockingStub(channel);

  // Vehicle settings
  String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
  DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
      .addAllAttributes(ImmutableList.of(
          DeliveryVehicleAttribute.newBuilder().setKey("zone").setValue("1B").build(),
          DeliveryVehicleAttribute.newBuilder().setKey("available-at-night").setValue("true").build()))
      .build();

  // DeliveryVehicle request
  UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
    UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
        .setName(vehicleName)
        .setDeliveryVehicle(myDeliveryVehicle)
        .setUpdateMask(FieldMask.newBuilder()
            .addPaths("attributes"))
        .build();

  try {
    DeliveryVehicle updatedDeliveryVehicle =
        deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
  } catch (StatusRuntimeException e) {
    Status s = e.getStatus();
    switch (s.getCode()) {
       case NOT_FOUND:
         break;
       case PERMISSION_DENIED:
         break;
    }
    return;
  }

  # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
  # environment
  curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=attributes" \
    -H "Content-type: application/json" \
    -H "Authorization: Bearer ${JWT}" \
    --data-binary @- << EOM
  {
      "attributes": [
        {"key": "zone", "value": "1B"},
        {"key": "available-at-night", "value": "true"}
      ]
  }
  EOM