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

توضّح هذه المقالة كيفية تعديل رحلة وإدارة حالتها، ما يتضمّن استخدام قناع حقل لضبط الحقول ذات الصلة برحلة. ويفترض هذا المستند أنّك أعددت 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;
}

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

يمكنك تحديد حالة الرحلة باستخدام إحدى قيم تعداد TripStatusenumeration. عند تغيير حالة الرحلة، مثلاً من 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.

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