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

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

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

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

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

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

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

استخدِم بيانات الاعتماد المناسبة لحساب الخدمة في مشروعك كما هو موضّح في Fleet Engine: أدوار حساب الخدمة.

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

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

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

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

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

يجب ضبط رحلة باستخدام رقم تعريف مركبة لكي يتمكّن 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.

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

• العثور على رحلات