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

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

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

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

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

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

• متد UpdateTrip() : gRPC یا REST
• پیام UpdateTripRequest : فقط gRPC

از اعتبارنامه‌های مناسب برای حساب سرویس پروژه خود، همانطور که در Fleet Engine: Service account roles توضیح داده شده است، استفاده کنید.

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

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

از ماسک‌های میدانی استفاده کنید

ماسک‌های فیلد راهی برای فراخوانی‌کنندگان API هستند تا فیلدهایی را که یک درخواست باید به‌روزرسانی کند، فهرست کنند. استفاده از ماسک فیلد از کارهای غیرضروری جلوگیری کرده و عملکرد را بهبود می‌بخشد. موتور ناوگان از ماسک‌های فیلد برای به‌روزرسانی فیلدها در تمام منابع استفاده می‌کند.

سفر را با شناسه وسیله نقلیه به روز کنید

شما باید یک سفر را با شناسه وسیله نقلیه پیکربندی کنید تا موتور ناوگان بتواند وسیله نقلیه را در طول مسیر خود ردیابی کند. نمونه کد زیر نحوه به‌روزرسانی سفر با شناسه وسیله نقلیه را نشان می‌دهد.

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، چه برای اندروید و چه برای iOS ، مشاهده کنید.

قدم بعدی چیست؟

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