@googlemaps/fleetengine-delivery 0.1.0

package/build/protos/google/maps/fleetengine/delivery/v1/delivery_api.proto

@@ -0,0 +1,597 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package maps.fleetengine.delivery.v1;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/api/routing.proto";
+import "google/geo/type/viewport.proto";
+import "google/maps/fleetengine/delivery/v1/delivery_vehicles.proto";
+import "google/maps/fleetengine/delivery/v1/header.proto";
+import "google/maps/fleetengine/delivery/v1/task_tracking_info.proto";
+import "google/maps/fleetengine/delivery/v1/tasks.proto";
+import "google/protobuf/field_mask.proto";
+
+option csharp_namespace = "Google.Maps.FleetEngine.Delivery.V1";
+option go_package = "cloud.google.com/go/maps/fleetengine/delivery/apiv1/deliverypb;deliverypb";
+option java_multiple_files = true;
+option java_outer_classname = "DeliveryApi";
+option java_package = "google.maps.fleetengine.delivery.v1";
+option objc_class_prefix = "CFED";
+option (google.api.resource_definition) = {
+  type: "fleetengine.googleapis.com/Provider"
+  pattern: "providers/{provider}"
+};
+
+// The Last Mile Delivery service.
+service DeliveryService {
+  option (google.api.default_host) = "fleetengine.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform";
+
+  // Creates and returns a new `DeliveryVehicle`.
+  rpc CreateDeliveryVehicle(CreateDeliveryVehicleRequest)
+      returns (DeliveryVehicle) {
+    option (google.api.http) = {
+      post: "/v1/{parent=providers/*}/deliveryVehicles"
+      body: "delivery_vehicle"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "parent"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) =
+        "parent,delivery_vehicle,delivery_vehicle_id";
+  }
+
+  // Returns the specified `DeliveryVehicle` instance.
+  rpc GetDeliveryVehicle(GetDeliveryVehicleRequest) returns (DeliveryVehicle) {
+    option (google.api.http) = {
+      get: "/v1/{name=providers/*/deliveryVehicles/*}"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "name"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Writes updated `DeliveryVehicle` data to Fleet Engine, and assigns
+  // `Tasks` to the `DeliveryVehicle`. You cannot update the name of the
+  // `DeliveryVehicle`. You *can* update `remaining_vehicle_journey_segments`
+  // though, but it must contain all of the `VehicleJourneySegment`s currently
+  // 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) {
+    option (google.api.http) = {
+      patch: "/v1/{delivery_vehicle.name=providers/*/deliveryVehicles/*}"
+      body: "delivery_vehicle"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "delivery_vehicle.name"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) = "delivery_vehicle,update_mask";
+  }
+
+  // Creates and returns a batch of new `Task` objects.
+  rpc BatchCreateTasks(BatchCreateTasksRequest)
+      returns (BatchCreateTasksResponse) {
+    option (google.api.http) = {
+      post: "/v1/{parent=providers/*}/tasks:batchCreate"
+      body: "*"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "parent"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+  }
+
+  // Creates and returns a new `Task` object.
+  rpc CreateTask(CreateTaskRequest) returns (Task) {
+    option (google.api.http) = {
+      post: "/v1/{parent=providers/*}/tasks"
+      body: "task"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "parent"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) = "parent,task,task_id";
+  }
+
+  // Gets information about a `Task`.
+  rpc GetTask(GetTaskRequest) returns (Task) {
+    option (google.api.http) = {
+      get: "/v1/{name=providers/*/tasks/*}"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "name"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Deprecated: Use `GetTaskTrackingInfo` instead.
+  rpc SearchTasks(SearchTasksRequest) returns (SearchTasksResponse) {
+    option deprecated = true;
+    option (google.api.http) = {
+      get: "/v1/{parent=providers/*}/tasks:search"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "parent"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) = "parent";
+  }
+
+  // Updates `Task` data.
+  rpc UpdateTask(UpdateTaskRequest) returns (Task) {
+    option (google.api.http) = {
+      patch: "/v1/{task.name=providers/*/tasks/*}"
+      body: "task"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "task.name"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) = "task,update_mask";
+  }
+
+  // Gets all `Task`s that meet the specified filtering criteria.
+  rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) {
+    option (google.api.http) = {
+      get: "/v1/{parent=providers/*}/tasks"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "parent"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) = "parent";
+  }
+
+  // Returns the specified `TaskTrackingInfo` instance.
+  rpc GetTaskTrackingInfo(GetTaskTrackingInfoRequest)
+      returns (TaskTrackingInfo) {
+    option (google.api.http) = {
+      get: "/v1/{name=providers/*/taskTrackingInfo/*}"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "name"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Gets all `DeliveryVehicle`s that meet the specified filtering criteria.
+  rpc ListDeliveryVehicles(ListDeliveryVehiclesRequest)
+      returns (ListDeliveryVehiclesResponse) {
+    option (google.api.http) = {
+      get: "/v1/{parent=providers/*}/deliveryVehicles"
+    };
+    option (google.api.routing) = {
+      routing_parameters {
+        field: "parent"
+        path_template: "{provider_id=providers/*}"
+      }
+    };
+    option (google.api.method_signature) = "parent";
+  }
+}
+
+// The `CreateDeliveryVehicle` request message.
+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`.
+  string parent = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // 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.
+  // * Normalized according to [Unicode Normalization Form C]
+  // (http://www.unicode.org/reports/tr15/).
+  // * May not contain any of the following ASCII characters: '/', ':', '?',
+  // ',', 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:
+  //
+  // * last_location
+  // * attributes
+  //
+  // Note: The DeliveryVehicle's `name` field is ignored. All other
+  // DeliveryVehicle fields must not be set; otherwise, an error is returned.
+  DeliveryVehicle delivery_vehicle = 5 [(google.api.field_behavior) = REQUIRED];
+}
+
+// The `GetDeliveryVehicle` request message.
+message GetDeliveryVehicleRequest {
+  // Optional. The standard Delivery API request header.
+  DeliveryRequestHeader header = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. Must be in the format
+  // `providers/{provider}/deliveryVehicles/{delivery_vehicle}`.
+  // 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) = {
+      type: "fleetengine.googleapis.com/DeliveryVehicle"
+    }
+  ];
+}
+
+// The `ListDeliveryVehicles` request message.
+message ListDeliveryVehiclesRequest {
+  // 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`.
+  string parent = 3 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "fleetengine.googleapis.com/DeliveryVehicle"
+    }
+  ];
+
+  // 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.
+  //
+  // When paginating, all other parameters provided to `ListDeliveryVehicles`
+  // must match the call that provided the page token.
+  string page_token = 5 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A filter query to apply when listing delivery vehicles. See
+  // http://aip.dev/160 for examples of the filter syntax. If you don't specify
+  // a value, or if you specify an empty string for the filter, then all
+  // delivery vehicles are returned.
+  //
+  // Note that the only queries supported for `ListDeliveryVehicles` are
+  // on vehicle attributes (for example, `attributes.<key> = <value>` or
+  // `attributes.<key1> = <value1> AND attributes.<key2> = <value2>`). Also, all
+  // attributes are stored as strings, so the only supported comparisons against
+  // attributes are string comparisons. In order to compare against number or
+  // boolean values, the values must be explicitly quoted to be treated as
+  // strings (for example, `attributes.<key> = "10"` or
+  // `attributes.<key> = "true"`).
+  //
+  // The maximum number of restrictions allowed in a filter query is 50. A
+  // restriction is a part of the query of the form
+  // `attribute.<KEY> <COMPARATOR> <VALUE>`, for example `attributes.foo = bar`
+  // is 1 restriction.
+  string filter = 6 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A filter that limits the vehicles returned to those whose last
+  // known location was in the rectangular area defined by the viewport.
+  google.geo.type.Viewport viewport = 7
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The `ListDeliveryVehicles` response message.
+message ListDeliveryVehiclesResponse {
+  // The set of delivery vehicles that meet the requested filtering criteria.
+  // When no filter is specified, the request returns all delivery vehicles. A
+  // successful response can also be empty. An empty response indicates that no
+  // delivery vehicles were found meeting the requested filter criteria.
+  repeated DeliveryVehicle delivery_vehicles = 1;
+
+  // You can pass this token in the `ListDeliveryVehiclesRequest` to continue to
+  // list results. When all of the results are returned, this field won't be in
+  // the response, or it will be an empty string.
+  string next_page_token = 2;
+
+  // The total number of delivery vehicles that match the request criteria,
+  // across all pages.
+  int64 total_size = 3;
+}
+
+// The `UpdateDeliveryVehicle` request message.
+message UpdateDeliveryVehicleRequest {
+  // Optional. The standard Delivery API request header.
+  DeliveryRequestHeader header = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. The `DeliveryVehicle` entity update to apply.
+  // Note: You cannot update the name of the `DeliveryVehicle`.
+  DeliveryVehicle delivery_vehicle = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. A field mask that indicates which `DeliveryVehicle` fields to
+  // update. Note that the update_mask must contain at least one field.
+  //
+  // 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];
+}
+
+// The `BatchCreateTask` request message.
+message BatchCreateTasksRequest {
+  // Optional. The standard Delivery API request header.
+  // Note: If you set this field, then the header field in the
+  // `CreateTaskRequest` messages must either be empty, or it must match this
+  // 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
+  // `CreateTaskRequest` messages must either  be empty, or it must match this
+  // field.
+  string parent = 3 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "fleetengine.googleapis.com/Task"
+    }
+  ];
+
+  // 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];
+}
+
+// The `BatchCreateTask` response message.
+message BatchCreateTasksResponse {
+  // The created Tasks.
+  repeated Task tasks = 1;
+}
+
+// The `CreateTask` request message.
+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`.
+  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:
+  //
+  // * Must be a valid Unicode string.
+  // * Limited to a maximum length of 64 characters.
+  // * Normalized according to [Unicode Normalization Form C]
+  // (http://www.unicode.org/reports/tr15/).
+  // * May not contain any of the following ASCII characters: '/', ':', '?',
+  // ',', or '#'.
+  string task_id = 5 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The Task entity to create.
+  // When creating a Task, the following fields are required:
+  //
+  // * `type`
+  // * `state` (must be set to `OPEN`)
+  // * `tracking_id` (must not be set for `UNAVAILABLE` or `SCHEDULED_STOP`
+  // tasks, but required for all other task types)
+  // * `planned_location` (optional for `UNAVAILABLE` tasks)
+  // * `task_duration`
+  //
+  // Note: The Task's `name` field is ignored. All other Task fields must not be
+  // set; otherwise, an error is returned.
+  Task task = 4 [(google.api.field_behavior) = REQUIRED];
+}
+
+// The `GetTask` request message.
+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`.
+  string name = 3 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "fleetengine.googleapis.com/Task"
+    }
+  ];
+}
+
+// Deprecated: Issue `GetTaskTrackingInfoRequest`s to `GetTaskTrackingInfo`
+// instead.
+message SearchTasksRequest {
+  option deprecated = true;
+
+  // 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`.
+  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:
+  //
+  // * Must be a valid Unicode string.
+  // * Limited to a maximum length of 64 characters.
+  // * Normalized according to [Unicode Normalization Form C]
+  // (http://www.unicode.org/reports/tr15/).
+  // * May not contain any of the following ASCII characters: '/', ':', '?',
+  // ',', 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.
+  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.
+  //
+  // When paginating, all other parameters provided to `SearchTasks` must match
+  // the call that provided the page token.
+  string page_token = 6 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The `SearchTasks` response. It contains the set of Tasks that meet the search
+// criteria in the `SearchTasksRequest`.
+message SearchTasksResponse {
+  option deprecated = true;
+
+  // The set of Tasks for the requested `tracking_id`. A successful response can
+  // also be empty. An empty response indicates that no Tasks are associated
+  // with the supplied `tracking_id`.
+  repeated Task tasks = 1;
+
+  // Pass this token in the `SearchTasksRequest` to continue to
+  // list results. If all results have been returned, then this field is either
+  // an empty string, or it doesn't appear in the response.
+  string next_page_token = 2;
+}
+
+// The `UpdateTask` request message.
+message UpdateTaskRequest {
+  // Optional. The standard Delivery API request header.
+  DeliveryRequestHeader header = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. The Task associated with the update.
+  // The following fields are maintained by Fleet Engine. Do not update
+  // them using `Task.update`.
+  //
+  //   * `last_location`.
+  //   * `last_location_snappable`.
+  //   * `name`.
+  //   * `remaining_vehicle_journey_segments`.
+  //   * `task_outcome_location_source`.
+  //
+  // Note: You cannot change the value of `task_outcome` once you set it.
+  //
+  // If the Task has been assigned to a delivery vehicle, then don't set the
+  // Task state to CLOSED using `Task.update`. Instead, remove the `VehicleStop`
+  // that contains the Task from the delivery vehicle, which automatically sets
+  // the Task state to CLOSED.
+  Task task = 3 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The field mask that indicates which Task fields to update.
+  // Note: The `update_mask` must contain at least one field.
+  //
+  // 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];
+}
+
+// The `ListTasks` request message.
+message ListTasksRequest {
+  // 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`.
+  string parent = 3 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "fleetengine.googleapis.com/Task"
+    }
+  ];
+
+  // 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.
+  // You can provide this to retrieve the subsequent page.
+  //
+  // When paginating, all other parameters provided to `ListTasks` must match
+  // 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
+  // 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];
+}
+
+// The `ListTasks` response that contains the set of Tasks that meet the filter
+// criteria in the `ListTasksRequest`.
+message ListTasksResponse {
+  // The set of Tasks that meet the requested filtering criteria. When no filter
+  // is specified, the request returns all tasks. A successful response can also
+  // be empty. An empty response indicates that no Tasks were found meeting the
+  // requested filter criteria.
+  repeated Task tasks = 1;
+
+  // Pass this token in the `ListTasksRequest` to continue to list results.
+  // If all results have been returned, then this field is either an empty
+  // string, or it doesn't appear in the response.
+  string next_page_token = 2;
+
+  // The total number of Tasks that match the request criteria, across all
+  // pages.
+  int64 total_size = 3;
+}
+
+// The `GetTaskTrackingInfoRequest` request message.
+message GetTaskTrackingInfoRequest {
+  // Optional. The standard Delivery API request header.
+  DeliveryRequestHeader header = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. Must be in the format
+  // `providers/{provider}/taskTrackingInfo/{tracking_id}`. The `provider`
+  // must be the Google Cloud Project ID, and the `tracking_id` must be the
+  // tracking ID associated with the task. An example name can be
+  // `providers/sample-cloud-project/taskTrackingInfo/sample-tracking-id`.
+  string name = 3 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "fleetengine.googleapis.com/TaskTrackingInfo"
+    }
+  ];
+}