이 문서에서는 여행을 업데이트하고 상태를 관리하는 방법을 설명합니다. 여기에는 필드 마스크를 사용하여 여행의 관련 필드를 설정하는 작업이 포함됩니다. 이 가이드에서는 이 사이트에 설명된 대로 Fleet Engine을 설정했고 여정에 할당된 차량을 사용하고 있다고 가정합니다.
단일 목적지 여행 만들기의 여행 필드에 설명된 여행 필드를 업데이트할 수 있습니다. 예를 들어 이동을 만든 후 먼저 차량을 찾은 다음 이동을 수행할 차량과 연결되도록 이동의 vehicle_id 필드를 업데이트하는 것이 일반적입니다.
필드 마스크 사용
필드 마스크는 API 호출자가 요청이 가져오거나 업데이트해야 하는 필드를 나열하는 방법입니다. FieldMask를 사용하면 불필요한 작업을 방지하고 성능을 개선할 수 있습니다. Fleet Engine은 모든 리소스에서 필드를 업데이트하는 데 필드 마스크를 사용합니다.
차량 ID로 여정 업데이트
Fleet Engine이 경로를 따라 차량을 추적할 수 있도록 차량 ID로 여정을 구성해야 합니다. 다음 코드 샘플은 차량 ID로 이동을 업데이트하는 방법을 보여줍니다.
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 전에 성공했습니다.
[[["이해하기 쉬움","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(UTC)"],[[["\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)"]]
