با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
این سند نحوه به‌روزرسانی یک سفر و مدیریت وضعیت آن را شرح می‌دهد که شامل استفاده از یک ماسک میدانی برای تنظیم فیلدهای مربوطه برای یک سفر است. فرض بر این است که شما Fleet Engine را همانطور که در این سایت توضیح داده شده راه اندازی کرده اید و در حال کار با وسیله نقلیه ای هستید که به یک سفر اختصاص داده شده است.
اصول به روز رسانی سفر
سیستم شما از Fleet Engine برای به‌روزرسانی یک سفر در شرایط زیر استفاده می‌کند:
هنگام اختصاص یک وسیله نقلیه به سفر پس از ایجاد.
هنگامی که وضعیت سفر تغییر می کند؛ به عنوان مثال، هنگامی که وسیله نقلیه از ایستگاه های بین راهی عبور می کند.
وقتی فیلدهای سفر را به‌روزرسانی می‌کنید، مانند تعداد مسافران و نقطه خروج.
برای به‌روزرسانی یک سفر، با استفاده از gRPC و REST درخواست ارسال کنید.
می توانید هر یک از فیلدهای سفر را که در فیلدهای سفر در ایجاد یک سفر مقصد واحد توضیح داده شده است، به روز کنید. به عنوان مثال، پس از ایجاد یک سفر، این یک روش معمول است که ابتدا یک وسیله نقلیه را پیدا کنید و سپس فیلد trip vehicle_id به روز کنید تا آن را با وسیله نقلیه ای که سفر را انجام می دهد مرتبط کنید.
از ماسک های میدانی استفاده کنید
فیلد ماسک راهی برای تماس‌گیرندگان API برای فهرست کردن فیلدهایی است که یک درخواست باید یا به‌روزرسانی کند. استفاده از FieldMask از کارهای غیر ضروری جلوگیری می کند و عملکرد را بهبود می بخشد. Fleet Engine از ماسک‌های فیلد برای به‌روزرسانی فیلدها در تمام منابع استفاده می‌کند.
سفر را با شناسه وسیله نقلیه به روز کنید
شما باید یک سفر را با شناسه وسیله نقلیه پیکربندی کنید تا Fleet Engine بتواند وسیله نقلیه را در طول مسیر خود ردیابی کند. نمونه کد زیر نحوه به روز رسانی سفر با شناسه وسیله نقلیه را نشان می دهد.
staticfinalStringPROJECT_ID="my-rideshare-co-gcp-project";staticfinalStringTRIP_ID="trip-8241890";StringtripName="providers/"+PROJECT_ID+"/trips/"+TRIP_ID;TripServiceBlockingStubtripService=TripService.newBlockingStub(channel);// The trip settings to update.Triptrip=Trip.newBuilder().setVehicleId("8241890").build();// The trip update request.UpdateTripRequestupdateTripRequest=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{TripupdatedTrip=tripService.updateTrip(updateTripRequest);}catch(StatusRuntimeExceptione){Statuss=e.getStatus();switch(s.getCode()){caseNOT_FOUND:// Neither the trip nor vehicle exist.break;casePERMISSION_DENIED:break;}return;}
مدیریت وضعیت سفر برای سفرها
شما وضعیت یک سفر را با استفاده از یکی از مقادیر شمارش TripStatus مشخص می کنید. هنگامی که وضعیت سفر تغییر می کند. برای مثال از ENROUTE_TO_PICKUP تا ARRIVED_AT_PICKUP ، وضعیت سفر را در Fleet Engine به روز می کنید. چرخه عمر سفر همیشه با مقدار حالت NEW شروع می شود و با مقدار COMPLETE یا CANCELED به پایان می رسد.
نمونه به روز رسانی سفر
در زیر نحوه به‌روزرسانی وضعیت سفر برای یک سفر پشت سر هم در Fleet Engine نشان داده می‌شود.
staticfinalStringPROJECT_ID="my-rideshare-co-gcp-project";staticfinalStringTRIP_ID="trip-8241890";StringtripName="providers/"+PROJECT_ID+"/trips/"+TRIP_ID;TripServiceBlockingStubtripService=TripService.newBlockingStub(channel);// Trip settings to be updated.Triptrip=Trip.newBuilder().setTripStatus(TripStatus.ARRIVED_AT_PICKUP).build();// Trip update requestUpdateTripRequestupdateTripRequest=UpdateTripRequest.newBuilder().setName(tripName).setTrip(trip).setUpdateMask(FieldMask.newBuilder().addPaths("trip_status")).build();// Error handling.try{TripupdatedTrip=tripService.updateTrip(updateTripRequest);}catch(StatusRuntimeExceptione){Statuss=e.getStatus();switch(s.getCode()){caseNOT_FOUND:// The trip doesn't exist.break;caseFAILED_PRECONDITION:// The given trip status is invalid.break;casePERMISSION_DENIED:break;}return;}
نمونه های دیگری از نحوه به روز رسانی سفرها را می توانید در قسمت سایر انواع سفر مشاهده کنید.
خطاهای سفر را مدیریت کنید
هنگام به‌روزرسانی یا یافتن سفرهای موجود، ممکن است با خطای DEADLINE_EXCEEDED مواجه شوید که در این صورت وضعیت Fleet Engine ناشناخته است. برای بررسی این موضوع، ابتدا با استفاده از همان ID سفری که می‌خواهید به‌روزرسانی یا نظارت کنید، دوباره CreateTrip تماس بگیرید. این باید یک 201 (CREATED) یا 409 (CONFLICT) را برگرداند. در مورد دوم، درخواست قبلی قبل از DEADLINE_EXCEEDED با موفقیت انجام شد.
فهرست خطاهای شبکه را در Consumer SDK، چه برای Android یا iOS ببینید.
تاریخ آخرین به‌روزرسانی 2025-09-04 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین به‌روزرسانی 2025-09-04 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eFleet Engine allows you to update trip details like vehicle assignment, status changes, and passenger information using gRPC or REST.\u003c/p\u003e\n"],["\u003cp\u003eWhen updating trips, utilize field masks to specify the fields to be modified, enhancing performance and efficiency.\u003c/p\u003e\n"],["\u003cp\u003eYou manage a trip's state by updating its \u003ccode\u003eTripStatus\u003c/code\u003e field, reflecting the trip's progress from \u003ccode\u003eNEW\u003c/code\u003e to \u003ccode\u003eCOMPLETE\u003c/code\u003e or \u003ccode\u003eCANCELED\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eFor trips with a \u003ccode\u003eDEADLINE_EXCEEDED\u003c/code\u003e error, retry \u003ccode\u003eCreateTrip\u003c/code\u003e with the same trip ID to determine the previous request's outcome.\u003c/p\u003e\n"]]],["To update a trip in Fleet Engine, use the `UpdateTrip()` method via gRPC or REST, utilizing an `UpdateTripRequest` message and the appropriate service account credentials. Updates can include assigning a vehicle, changing the trip status, or modifying other fields. Field masks are used to specify which fields to update, improving efficiency. The `vehicle_id` can only be set when the trip is new, and the trip's state is managed via `TripStatus` values. Error handling is essential, especially for `DEADLINE_EXCEEDED` cases.\n"],null,["This document describes how to update a trip and manage its state, which\ninvolves using a field mask to set relevant fields for a trip. It assumes you\nhave set up Fleet Engine as described in this site and are working with a\nvehicle assigned to a trip.\n\nTrip update basics\n\nYour system uses Fleet Engine to update a trip in the following situations:\n\n- When assigning a vehicle to a trip after it's created.\n- When the status of the trip changes; for example, when the vehicle passes through waypoints.\n- When you update trip fields, such as the number of passengers and the drop-off point.\n\nTo update a trip, send a request using either gRPC and REST.\n\n- `UpdateTrip()` method: [gRPC](/maps/documentation/mobility/fleet-engine/reference/trips/rpc/maps.fleetengine.v1#maps.fleetengine.v1.TripService) or [REST](/maps/documentation/mobility/fleet-engine/reference/trips/rest/v1/providers.trips/update)\n- `UpdateTripRequest` message: [gRPC](/maps/documentation/mobility/fleet-engine/reference/trips/rpc/maps.fleetengine.v1#updatetriprequest) only\n\nUse the appropriate credentials for the service account of your project as\ndescribed in [Fleet Engine: Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts).\n\nUpdate trip fields\n\nYou can update any of the trip fields described in [Trip fields](/maps/documentation/mobility/fleet-engine/journeys/trips/create-trip#trip-fields) in **Create\na single destination trip** . For example, after you create a trip, it's a common\npractice to first find a vehicle and then update the trip `vehicle_id` field to\nassociate it with the vehicle that will carry out the trip.\n| **Important:** You can only set the vehicle_id for a **NEW** trip. If you want to changes vehicle for a trip, you must set the trip status to `NEW` and then assign the different vehicle.\n\nUse field masks\n\n\u003cbr /\u003e\n\nField masks are a way for API callers to list the fields that a request should\nor update. Using a [FieldMask](https://protobuf.dev/reference/protobuf/google.protobuf/#field-mask)\navoids unnecessary works and improves performance. Fleet Engine uses field masks\nfor updating fields across all resources.\n\nUpdate the trip with the vehicle ID\n\nYou must configure a trip with a vehicle ID so that the Fleet Engine can track\nthe vehicle along its route. The following code sample demonstrates how to\nupdate the trip with a vehicle ID. \n\n static final String PROJECT_ID = \"my-rideshare-co-gcp-project\";\n static final String TRIP_ID = \"trip-8241890\";\n\n String tripName = \"providers/\" + PROJECT_ID + \"/trips/\" + TRIP_ID;\n\n TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);\n\n // The trip settings to update.\n Trip trip = Trip.newBuilder()\n .setVehicleId(\"8241890\")\n .build();\n\n // The trip update request.\n UpdateTripRequest updateTripRequest =\n UpdateTripRequest.newBuilder() // No need for the header.\n .setName(tripName)\n .setTrip(trip)\n .setUpdateMask(FieldMask.newBuilder().addPaths(\"vehicle_id\"))\n .build();\n\n // Error handling.\n // If the Fleet Engine has both a trip and vehicle with IDs, and if the\n // credentials validate, then the service updates the trip.\n try {\n Trip updatedTrip = tripService.updateTrip(updateTripRequest);\n } catch (StatusRuntimeException e) {\n Status s = e.getStatus();\n switch (s.getCode()) {\n case NOT_FOUND: // Neither the trip nor vehicle exist.\n break;\n case PERMISSION_DENIED:\n break;\n }\n return;\n }\n\nManage trip state for trips\n\nYou specify the state of a trip using one of the [`TripStatus`](/maps/documentation/mobility/fleet-engine/reference/trips/rpc/maps.fleetengine.v1#tripstatus) enumeration\nvalues. When a trip's state changes; for example from `ENROUTE_TO_PICKUP` to\n`ARRIVED_AT_PICKUP`, you update the trip state in Fleet Engine. The trip\nlifecycle always begins with a state value of `NEW`, and ends with a value of\neither `COMPLETE` or `CANCELED`.\n\nExample trip update\n\nThe following demonstrates how to update the trip state for a back-to-back\ntrip in Fleet Engine. \n\n static final String PROJECT_ID = \"my-rideshare-co-gcp-project\";\n static final String TRIP_ID = \"trip-8241890\";\n\n String tripName = \"providers/\" + PROJECT_ID + \"/trips/\" + TRIP_ID;\n\n TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);\n\n // Trip settings to be updated.\n Trip trip = Trip.newBuilder()\n .setTripStatus(TripStatus.ARRIVED_AT_PICKUP)\n .build();\n\n // Trip update request\n UpdateTripRequest updateTripRequest = UpdateTripRequest.newBuilder()\n .setName(tripName)\n .setTrip(trip)\n .setUpdateMask(FieldMask.newBuilder().addPaths(\"trip_status\"))\n .build();\n\n // Error handling.\n try {\n Trip updatedTrip = tripService.updateTrip(updateTripRequest);\n } catch (StatusRuntimeException e) {\n Status s = e.getStatus();\n switch (s.getCode()) {\n case NOT_FOUND: // The trip doesn't exist.\n break;\n case FAILED_PRECONDITION: // The given trip status is invalid.\n break;\n case PERMISSION_DENIED:\n break;\n }\n return;\n }\n\nYou can see other examples of how to update trips in the **Other trip types**\nsection.\n\nHandle trip errors\n\nWhen updating or finding existing trips, you might encounter a case of a\n`DEADLINE_EXCEEDED` error, in which case the state of Fleet Engine is unknown.\nTo investigate this, first call `CreateTrip` again using the same trip ID you\nare trying to update or monitor. This should return either a 201 (CREATED) or\n409 (CONFLICT). In the latter case, the previous request succeeded before\n`DEADLINE_EXCEEDED`.\n\nSee the list of network errors in the Consumer SDK, either for [Android](/maps/documentation/mobility/journey-sharing/on-demand/android/share-journey#handle_consumer_sdk_errors) or\n[iOS](/maps/documentation/mobility/journey-sharing/on-demand/ios/share-journey#handle_consumer_sdk_errors).\n\nWhat's next\n\n- [Find trips](/maps/documentation/mobility/fleet-engine/journeys/trips/find-trip)"]]
