به‌روزرسانی سفرها و مدیریت وضعیت آن‌ها

این سند نحوه به‌روزرسانی سفر و مدیریت وضعیت آن را شرح می‌دهد که شامل استفاده از ماسک فیلد برای تنظیم فیلدهای مربوط به سفر است. فرض بر این است که Fleet Engine را همان‌طور که در این سایت شرح داده شده است راه‌اندازی کرده‌اید و با خودرویی کار می‌کنید که به سفری اختصاص داده شده است.

اصول به‌روزرسانی سفر

سیستم شما از Fleet Engine برای به‌روزرسانی سفر در شرایط زیر استفاده می‌کند:

• هنگام اختصاص دادن خودرو به سفر پس‌از ایجاد آن.
• وقتی وضعیت سفر تغییر می‌کند؛ برای مثال، وقتی خودرو از نقاط‌مسیر عبور می‌کند.
• وقتی فیلدهای سفر را به‌روز می‌کنید، مثلاً تعداد مسافران و محل پیاده شدن.

برای به‌روزرسانی سفر، بااستفاده از gRPC یا REST درخواست ارسال کنید.

• روش UpdateTrip(): gRPC یا REST
• پیام UpdateTripRequest: فقط gRPC

از اطلاعات کاربری مناسب برای حساب سرویس پروژه‌تان استفاده کنید، همان‌طور که در Fleet Engine: نقش‌های حساب سرویس شرح داده شده است.

به‌روزرسانی فیلدهای سفر

می‌توانید هرکدام از فیلدهای سفر را که در فیلدهای سفر در ایجاد سفر تک‌مقصدی شرح داده شده است به‌روز کنید. برای مثال، پس‌از ایجاد سفر، معمولاً ابتدا وسیله نقلیه پیدا می‌شود و سپس فیلد vehicle_id سفر به‌روز می‌شود تا با وسیله نقلیه‌ای که سفر را انجام خواهد داد مرتبط شود.

استفاده از پوشش فیلد

ماسک‌های فیلد روشی برای تماس‌گیرندگان API هستند تا فیلدهایی را که یک درخواست باید یا به‌روزرسانی کند، فهرست کنند. استفاده از 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 موفقیت‌آمیز بوده است.

فهرست خطاهای شبکه را در Consumer SDK برای Android یا iOS ببینید.

قدم بعدی چیست

• پیدا کردن سفرها