Skip to content

Commit

Permalink
docs: Updated documentation for a few fields with trips.proto and veh…
Browse files Browse the repository at this point in the history 
…icle_api.proto

PiperOrigin-RevId: 503189011
  • Loading branch information
@pull
Google APIs authored and pull[bot] committed Apr 11, 2024
1 parent 8ad619b commit 3f14d84
Show file tree
Hide file tree
Showing 8 changed files with 194 additions and 143 deletions.
46 changes: 29 additions & 17 deletions google/maps/fleetengine/delivery/v1/common.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,49 +86,61 @@ message DeliveryVehicleLocation {
google.protobuf.Timestamp update_time = 4;

// Output only. The time when the server received the location information.
google.protobuf.Timestamp server_time = 13 [(google.api.field_behavior) = OUTPUT_ONLY];
google.protobuf.Timestamp server_time = 13
[(google.api.field_behavior) = OUTPUT_ONLY];

// Provider of location data (for example, `GPS`).
DeliveryVehicleLocationSensor location_sensor = 11;

// Whether `location` is snapped to a road.
google.protobuf.BoolValue is_road_snapped = 27;

// Input only. Indicates whether the GPS sensor is enabled on the mobile device.
google.protobuf.BoolValue is_gps_sensor_enabled = 12 [(google.api.field_behavior) = INPUT_ONLY];
// Input only. Indicates whether the GPS sensor is enabled on the mobile
// device.
google.protobuf.BoolValue is_gps_sensor_enabled = 12
[(google.api.field_behavior) = INPUT_ONLY];

// Input only. Time (in seconds) since this location was first sent to the server.
// This will be zero for the first update. If the time is unknown
// (for example, when the app restarts), this value resets to zero.
google.protobuf.Int32Value time_since_update = 14 [(google.api.field_behavior) = INPUT_ONLY];
// Input only. Time (in seconds) since this location was first sent to the
// server. This will be zero for the first update. If the time is unknown (for
// example, when the app restarts), this value resets to zero.
google.protobuf.Int32Value time_since_update = 14
[(google.api.field_behavior) = INPUT_ONLY];

// Input only. Number of additional attempts to send this location to the server.
// If this value is zero, then it is not stale.
google.protobuf.Int32Value num_stale_updates = 15 [(google.api.field_behavior) = INPUT_ONLY];
// Input only. Number of additional attempts to send this location to the
// server. If this value is zero, then it is not stale.
google.protobuf.Int32Value num_stale_updates = 15
[(google.api.field_behavior) = INPUT_ONLY];

// Raw vehicle location (unprocessed by road-snapper).
google.type.LatLng raw_location = 16;

// Input only. Timestamp associated with the raw location.
google.protobuf.Timestamp raw_location_time = 17 [(google.api.field_behavior) = INPUT_ONLY];
google.protobuf.Timestamp raw_location_time = 17
[(google.api.field_behavior) = INPUT_ONLY];

// Input only. Source of the raw location.
DeliveryVehicleLocationSensor raw_location_sensor = 28 [(google.api.field_behavior) = INPUT_ONLY];
DeliveryVehicleLocationSensor raw_location_sensor = 28
[(google.api.field_behavior) = INPUT_ONLY];

// Input only. Accuracy of `raw_location` as a radius, in meters.
google.protobuf.DoubleValue raw_location_accuracy = 25 [(google.api.field_behavior) = INPUT_ONLY];
google.protobuf.DoubleValue raw_location_accuracy = 25
[(google.api.field_behavior) = INPUT_ONLY];

// Input only. Supplemental location provided by the integrating app.
google.type.LatLng supplemental_location = 18 [(google.api.field_behavior) = INPUT_ONLY];
google.type.LatLng supplemental_location = 18
[(google.api.field_behavior) = INPUT_ONLY];

// Input only. Timestamp associated with the supplemental location.
google.protobuf.Timestamp supplemental_location_time = 19 [(google.api.field_behavior) = INPUT_ONLY];
google.protobuf.Timestamp supplemental_location_time = 19
[(google.api.field_behavior) = INPUT_ONLY];

// Input only. Source of the supplemental location.
DeliveryVehicleLocationSensor supplemental_location_sensor = 20 [(google.api.field_behavior) = INPUT_ONLY];
DeliveryVehicleLocationSensor supplemental_location_sensor = 20
[(google.api.field_behavior) = INPUT_ONLY];

// Input only. Accuracy of `supplemental_location` as a radius, in meters.
google.protobuf.DoubleValue supplemental_location_accuracy = 21 [(google.api.field_behavior) = INPUT_ONLY];
google.protobuf.DoubleValue supplemental_location_accuracy = 21
[(google.api.field_behavior) = INPUT_ONLY];

// Deprecated: Use `is_road_snapped` instead.
bool road_snapped = 26 [deprecated = true];
Expand Down
105 changes: 57 additions & 48 deletions google/maps/fleetengine/delivery/v1/delivery_api.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,8 @@ service DeliveryService {
option (google.api.default_host) = "fleetengine.googleapis.com";

// Creates and returns a new `DeliveryVehicle`.
rpc CreateDeliveryVehicle(CreateDeliveryVehicleRequest) returns (DeliveryVehicle) {
rpc CreateDeliveryVehicle(CreateDeliveryVehicleRequest)
returns (DeliveryVehicle) {
option (google.api.http) = {
post: "/v1/{parent=providers/*}/deliveryVehicles"
body: "delivery_vehicle"
Expand All @@ -53,7 +54,8 @@ service DeliveryService {
path_template: "{provider_id=providers/*}"
}
};
option (google.api.method_signature) = "parent,delivery_vehicle,delivery_vehicle_id";
option (google.api.method_signature) =
"parent,delivery_vehicle,delivery_vehicle_id";
}

// Returns the specified `DeliveryVehicle` instance.
Expand All @@ -77,7 +79,8 @@ service DeliveryService {
// on the `DeliveryVehicle`. The `task_id`s are retrieved from
// `remaining_vehicle_journey_segments`, and their corresponding `Tasks` are
// assigned to the `DeliveryVehicle` if they have not yet been assigned.
rpc UpdateDeliveryVehicle(UpdateDeliveryVehicleRequest) returns (DeliveryVehicle) {
rpc UpdateDeliveryVehicle(UpdateDeliveryVehicleRequest)
returns (DeliveryVehicle) {
option (google.api.http) = {
patch: "/v1/{delivery_vehicle.name=providers/*/deliveryVehicles/*}"
body: "delivery_vehicle"
Expand All @@ -92,7 +95,8 @@ service DeliveryService {
}

// Creates and returns a batch of new `Task` objects.
rpc BatchCreateTasks(BatchCreateTasksRequest) returns (BatchCreateTasksResponse) {
rpc BatchCreateTasks(BatchCreateTasksRequest)
returns (BatchCreateTasksResponse) {
option (google.api.http) = {
post: "/v1/{parent=providers/*}/tasks:batchCreate"
body: "*"
Expand Down Expand Up @@ -178,7 +182,8 @@ service DeliveryService {
}

// Gets all `DeliveryVehicle`s that meet the specified filtering criteria.
rpc ListDeliveryVehicles(ListDeliveryVehiclesRequest) returns (ListDeliveryVehiclesResponse) {
rpc ListDeliveryVehicles(ListDeliveryVehiclesRequest)
returns (ListDeliveryVehiclesResponse) {
option (google.api.http) = {
get: "/v1/{parent=providers/*}/deliveryVehicles"
};
Expand All @@ -197,12 +202,12 @@ message CreateDeliveryVehicleRequest {
// Optional. The standard Delivery API request header.
DeliveryRequestHeader header = 1 [(google.api.field_behavior) = OPTIONAL];

// Required. Must be in the format `providers/{provider}`. The provider must be the
// Google Cloud Project ID. For example, `sample-cloud-project`.
// Required. Must be in the format `providers/{provider}`. The provider must
// be the Google Cloud Project ID. For example, `sample-cloud-project`.
string parent = 3 [(google.api.field_behavior) = REQUIRED];

// Required. The Delivery Vehicle ID must be unique and subject to the following
// restrictions:
// Required. The Delivery Vehicle ID must be unique and subject to the
// following restrictions:
//
// * Must be a valid Unicode string.
// * Limited to a maximum length of 64 characters.
Expand All @@ -212,8 +217,8 @@ message CreateDeliveryVehicleRequest {
// ',', or '#'.
string delivery_vehicle_id = 4 [(google.api.field_behavior) = REQUIRED];

// Required. The `DeliveryVehicle` entity to create. When creating a new delivery
// vehicle, you may set the following optional fields:
// Required. The `DeliveryVehicle` entity to create. When creating a new
// delivery vehicle, you may set the following optional fields:
//
// * last_location
// * attributes
Expand Down Expand Up @@ -256,13 +261,13 @@ message ListDeliveryVehiclesRequest {
}
];

// Optional. The maximum number of vehicles to return. The service may return fewer than
// this number. If you don't specify this number, then the server determines
// the number of results to return.
// Optional. The maximum number of vehicles to return. The service may return
// fewer than this number. If you don't specify this number, then the server
// determines the number of results to return.
int32 page_size = 4 [(google.api.field_behavior) = OPTIONAL];

// Optional. A page token, received from a previous `ListDeliveryVehicles` call. You
// must provide this in order to retrieve the subsequent page.
// Optional. A page token, received from a previous `ListDeliveryVehicles`
// call. You must provide this in order to retrieve the subsequent page.
//
// When paginating, all other parameters provided to `ListDeliveryVehicles`
// must match the call that provided the page token.
Expand All @@ -288,11 +293,12 @@ message ListDeliveryVehiclesRequest {
// is 1 restriction.
string filter = 6 [(google.api.field_behavior) = OPTIONAL];

// Optional. A filter that limits the search area to a rectangle defined by the
// northeast and southwest corner points.
// Optional. A filter that limits the search area to a rectangle defined by
// the northeast and southwest corner points.
//
// When defined, only vehicles located within the search area are returned.
google.geo.type.Viewport viewport = 7 [(google.api.field_behavior) = OPTIONAL];
google.geo.type.Viewport viewport = 7
[(google.api.field_behavior) = OPTIONAL];
}

// The `ListDeliveryVehicles` response message.
Expand Down Expand Up @@ -327,7 +333,8 @@ message UpdateDeliveryVehicleRequest {
//
// This is a comma-separated list of fully qualified names of fields. Example:
// `"remaining_vehicle_journey_segments"`.
google.protobuf.FieldMask update_mask = 4 [(google.api.field_behavior) = REQUIRED];
google.protobuf.FieldMask update_mask = 4
[(google.api.field_behavior) = REQUIRED];
}

// The `BatchCreateTask` request message.
Expand All @@ -338,9 +345,9 @@ message BatchCreateTasksRequest {
// field.
DeliveryRequestHeader header = 1 [(google.api.field_behavior) = OPTIONAL];

// Required. The parent resource shared by all tasks. This value must be in the format
// `providers/{provider}`. The `provider` must be the Google Cloud Project ID.
// For example, `sample-cloud-project`. The parent field in the
// Required. The parent resource shared by all tasks. This value must be in
// the format `providers/{provider}`. The `provider` must be the Google Cloud
// Project ID. For example, `sample-cloud-project`. The parent field in the
// `CreateTaskRequest` messages must either be empty, or it must match this
// field.
string parent = 3 [
Expand All @@ -352,7 +359,8 @@ message BatchCreateTasksRequest {

// Required. The request message that specifies the resources to create.
// Note: You can create a maximum of 500 tasks in a batch.
repeated CreateTaskRequest requests = 4 [(google.api.field_behavior) = REQUIRED];
repeated CreateTaskRequest requests = 4
[(google.api.field_behavior) = REQUIRED];
}

// The `BatchCreateTask` response message.
Expand All @@ -366,14 +374,14 @@ message CreateTaskRequest {
// Optional. The standard Delivery API request header.
DeliveryRequestHeader header = 1 [(google.api.field_behavior) = OPTIONAL];

// Required. Must be in the format `providers/{provider}`. The `provider` must be the
// Google Cloud Project ID. For example, `sample-cloud-project`.
// Required. Must be in the format `providers/{provider}`. The `provider` must
// be the Google Cloud Project ID. For example, `sample-cloud-project`.
string parent = 3 [(google.api.field_behavior) = REQUIRED];

// Required. The Task ID must be unique, but it should be not a shipment tracking ID. To
// store a shipment tracking ID, use the `tracking_id` field. Note that
// multiple tasks can have the same `tracking_id`. Task IDs are subject to the
// following restrictions:
// Required. The Task ID must be unique, but it should be not a shipment
// tracking ID. To store a shipment tracking ID, use the `tracking_id` field.
// Note that multiple tasks can have the same `tracking_id`. Task IDs are
// subject to the following restrictions:
//
// * Must be a valid Unicode string.
// * Limited to a maximum length of 64 characters.
Expand Down Expand Up @@ -403,8 +411,9 @@ message GetTaskRequest {
// Optional. The standard Delivery API request header.
DeliveryRequestHeader header = 1 [(google.api.field_behavior) = OPTIONAL];

// Required. Must be in the format `providers/{provider}/tasks/{task}`. The `provider`
// must be the Google Cloud Project ID. For example, `sample-cloud-project`.
// Required. Must be in the format `providers/{provider}/tasks/{task}`. The
// `provider` must be the Google Cloud Project ID. For example,
// `sample-cloud-project`.
string name = 3 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
Expand All @@ -423,8 +432,8 @@ message SearchTasksRequest {
// `sample-cloud-project`.
string parent = 3 [(google.api.field_behavior) = REQUIRED];

// Required. The identifier of the set of related Tasks being requested. Tracking IDs
// are subject to the following restrictions:
// Required. The identifier of the set of related Tasks being requested.
// Tracking IDs are subject to the following restrictions:
//
// * Must be a valid Unicode string.
// * Limited to a maximum length of 64 characters.
Expand All @@ -434,13 +443,13 @@ message SearchTasksRequest {
// ',', or '#'.
string tracking_id = 4 [(google.api.field_behavior) = REQUIRED];

// Optional. The maximum number of Tasks to return. The service may return fewer than
// this value. If you don't specify this value, then the server determines the
// number of results to return.
// Optional. The maximum number of Tasks to return. The service may return
// fewer than this value. If you don't specify this value, then the server
// determines the number of results to return.
int32 page_size = 5 [(google.api.field_behavior) = OPTIONAL];

// Optional. A page token, received from a previous `SearchTasks` call. You must
// provide this value to retrieve the subsequent page.
// Optional. A page token, received from a previous `SearchTasks` call. You
// must provide this value to retrieve the subsequent page.
//
// When paginating, all other parameters provided to `SearchTasks` must match
// the call that provided the page token.
Expand Down Expand Up @@ -489,7 +498,8 @@ message UpdateTaskRequest {
//
// This is a comma-separated list of fully qualified names of fields. Example:
// `"task_outcome,task_outcome_time,task_outcome_location"`.
google.protobuf.FieldMask update_mask = 4 [(google.api.field_behavior) = REQUIRED];
google.protobuf.FieldMask update_mask = 4
[(google.api.field_behavior) = REQUIRED];
}

// The `ListTasks` request message.
Expand All @@ -507,9 +517,9 @@ message ListTasksRequest {
}
];

// Optional. The maximum number of Tasks to return. The service may return fewer than
// this value. If you don't specify this value, then the server determines the
// number of results to return.
// Optional. The maximum number of Tasks to return. The service may return
// fewer than this value. If you don't specify this value, then the server
// determines the number of results to return.
int32 page_size = 4 [(google.api.field_behavior) = OPTIONAL];

// Optional. A page token received from a previous `ListTasks` call.
Expand All @@ -519,11 +529,10 @@ message ListTasksRequest {
// the call that provided the page token.
string page_token = 5 [(google.api.field_behavior) = OPTIONAL];

// Optional. A filter query to apply when listing Tasks. See http://aip.dev/160 for
// examples of filter syntax. If you don't specify a value, or if you filter
// on an empty string, then all Tasks are returned. For information about the
// Task properties that you can filter on, see
// [Task
// Optional. A filter query to apply when listing Tasks. See
// http://aip.dev/160 for examples of filter syntax. If you don't specify a
// value, or if you filter on an empty string, then all Tasks are returned.
// For information about the Task properties that you can filter on, see [Task
// list](/maps/documentation/transportation-logistics/last-mile-fleet-solution/fleet-performance/fleet-engine/deliveries_api#list_tasks).
string filter = 6 [(google.api.field_behavior) = OPTIONAL];
}
Expand Down
Loading

0 comments on commit 3f14d84

Please sign in to comment.