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

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

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