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

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

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

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

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

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

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

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

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

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

ملاحظة مهمة: يمكنك ضبط vehicle_id لرحلة جديدة فقط. إذا أردت تغيير المركبة في رحلة، عليك ضبط حالة الرحلة على NEW ثم تحديد المركبة المختلفة.

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

تتيح أقنعة الحقول لمستخدمي واجهة برمجة التطبيقات إدراج الحقول التي يجب أن يتضمّنها الطلب أو يتم تعديلها. يؤدي استخدام 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 (تم الإنشاء) أو 409 (تعارض). في الحالة الأخيرة، نجح الطلب السابق قبل DEADLINE_EXCEEDED.

يمكنك الاطّلاع على قائمة بأخطاء الشبكة في حزمة Consumer SDK، سواء لنظام التشغيل Android أو iOS.

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

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