تعديل الرحلات وإدارة حالتها

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

أساسيات تعديلات الرحلة

يستخدم نظامك Fleet Engine لتعديل رحلة في الحالات التالية:

  • عند إسناد مركبة إلى رحلة بعد إنشائها
  • عند تغيُّر حالة الرحلة، على سبيل المثال، عندما تمر المركبة بنقاط الطريق
  • عند تعديل حقول الرحلة، مثل عدد الركّاب و نقطة الاستلام

لتعديل رحلة، أرسِل طلبًا باستخدام gRPC وREST.

  • طريقة UpdateTrip(): gRPC أو REST
  • رسالة UpdateTripRequest: gRPC فقط

استخدِم بيانات الاعتماد المناسبة لحساب الخدمة في مشروعك كما هو описан في مقالة Fleet Engine: أدوار حسابات الخدمة.

تعديل حقول الرحلة

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

استخدام أقنعة الحقول

وتعدّ أقنعة الحقول طريقة تتيح لمُطلِبي البيانات من واجهة برمجة التطبيقات إدراج الحقول التي يجب أن يُجري عليها الطلب تعديلات أو يُجري فيها عمليات بحث. يؤدي استخدام FieldMask إلى تجنُّب الأعمال غير الضرورية وتحسين الأداء. يستخدم Fleet Engine أقنعة الحقول لتعديل الحقول في جميع الموارد.

تعديل الرحلة باستخدام رقم تعريف المركبة

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

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// The trip settings to update.
Trip trip = Trip.newBuilder()
    .setVehicleId("8241890")
    .build();

// The trip update request.
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()      // No need for the header.
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(FieldMask.newBuilder().addPaths("vehicle_id"))
        .build();

// Error handling.
// If the Fleet Engine has both a trip and vehicle with IDs, and if the
// credentials validate, then the service updates the trip.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:                    // Neither the trip nor vehicle exist.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

إدارة حالة الرحلات

يمكنك تحديد حالة الرحلة باستخدام إحدى قيم التعداد TripStatus. عند تغيُّر حالة رحلة، على سبيل المثال من ENROUTE_TO_PICKUP إلى ARRIVED_AT_PICKUP، عليك تعديل حالة الرحلة في Fleet Engine. تبدأ دورة حياة الرحلة دائمًا بقيمة الحالة NEW، وتنتهي بقيمة COMPLETE أو CANCELED.

مثال على تعديل رحلة

توضِّح الخطوات التالية كيفية تعديل حالة رحلة متتالية في Fleet Engine.

static final String PROJECT_ID = "my-rideshare-co-gcp-project";
static final String TRIP_ID = "trip-8241890";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to be updated.
Trip trip = Trip.newBuilder()
    .setTripStatus(TripStatus.ARRIVED_AT_PICKUP)
    .build();

// Trip update request
UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()
    .setName(tripName)
    .setTrip(trip)
    .setUpdateMask(FieldMask.newBuilder().addPaths("trip_status"))
    .build();

// Error handling.
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:            // The trip doesn't exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

يمكنك الاطّلاع على أمثلة أخرى حول كيفية تعديل الرحلات في قسم أنواع الرحلات الأخرى.

التعامل مع أخطاء الرحلات

عند تعديل الرحلات الحالية أو العثور عليها، قد تواجه حالة خطأ DEADLINE_EXCEEDED، وفي هذه الحالة تكون حالة Fleet Engine غير معروفة. للتحقيق في هذه المشكلة، يُرجى أولاً الاتصال بـ "CreateTrip" مرة أخرى باستخدام رقم تعريف الرحلة نفسه الذي تحاول تعديله أو مراقبته. من المفترض أن يعرض هذا الإجراء إما 201 (CREATED) أو 409 (CONFLICT). في الحالة الأخيرة، تمكّن الطلب السابق من إتمام عملية الربط قبل DEADLINE_EXCEEDED.

اطّلِع على قائمة أخطاء الشبكة في حزمة تطوير البرامج (SDK) للمستهلك، سواءً لنظام التشغيل Android أو iOS.

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