google-maps-fleet_engine-delivery-v1 0.a → 0.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (41) hide show
  1. checksums.yaml +4 -4
  2. data/.yardopts +12 -0
  3. data/AUTHENTICATION.md +122 -0
  4. data/README.md +144 -8
  5. data/lib/google/maps/fleet_engine/delivery/v1/delivery_service/client.rb +1505 -0
  6. data/lib/google/maps/fleet_engine/delivery/v1/delivery_service/credentials.rb +49 -0
  7. data/lib/google/maps/fleet_engine/delivery/v1/delivery_service/paths.rb +100 -0
  8. data/lib/google/maps/fleet_engine/delivery/v1/delivery_service/rest/client.rb +1399 -0
  9. data/lib/google/maps/fleet_engine/delivery/v1/delivery_service/rest/service_stub.rb +666 -0
  10. data/lib/google/maps/fleet_engine/delivery/v1/delivery_service/rest.rb +54 -0
  11. data/lib/google/maps/fleet_engine/delivery/v1/delivery_service.rb +57 -0
  12. data/lib/google/maps/fleet_engine/delivery/v1/rest.rb +39 -0
  13. data/lib/google/maps/fleet_engine/delivery/v1/version.rb +8 -3
  14. data/lib/google/maps/fleet_engine/delivery/v1.rb +47 -0
  15. data/lib/google/maps/fleetengine/delivery/v1/common_pb.rb +57 -0
  16. data/lib/google/maps/fleetengine/delivery/v1/delivery_api_pb.rb +73 -0
  17. data/lib/google/maps/fleetengine/delivery/v1/delivery_api_services_pb.rb +71 -0
  18. data/lib/google/maps/fleetengine/delivery/v1/delivery_vehicles_pb.rb +61 -0
  19. data/lib/google/maps/fleetengine/delivery/v1/header_pb.rb +48 -0
  20. data/lib/google/maps/fleetengine/delivery/v1/task_tracking_info_pb.rb +58 -0
  21. data/lib/google/maps/fleetengine/delivery/v1/tasks_pb.rb +62 -0
  22. data/lib/google-maps-fleet_engine-delivery-v1.rb +21 -0
  23. data/proto_docs/README.md +4 -0
  24. data/proto_docs/google/api/client.rb +399 -0
  25. data/proto_docs/google/api/field_behavior.rb +85 -0
  26. data/proto_docs/google/api/launch_stage.rb +71 -0
  27. data/proto_docs/google/api/resource.rb +222 -0
  28. data/proto_docs/google/api/routing.rb +459 -0
  29. data/proto_docs/google/geo/type/viewport.rb +70 -0
  30. data/proto_docs/google/maps/fleetengine/delivery/v1/common.rb +251 -0
  31. data/proto_docs/google/maps/fleetengine/delivery/v1/delivery_api.rb +359 -0
  32. data/proto_docs/google/maps/fleetengine/delivery/v1/delivery_vehicles.rb +269 -0
  33. data/proto_docs/google/maps/fleetengine/delivery/v1/header.rb +113 -0
  34. data/proto_docs/google/maps/fleetengine/delivery/v1/task_tracking_info.rb +91 -0
  35. data/proto_docs/google/maps/fleetengine/delivery/v1/tasks.rb +281 -0
  36. data/proto_docs/google/protobuf/duration.rb +98 -0
  37. data/proto_docs/google/protobuf/field_mask.rb +229 -0
  38. data/proto_docs/google/protobuf/timestamp.rb +127 -0
  39. data/proto_docs/google/protobuf/wrappers.rb +121 -0
  40. data/proto_docs/google/type/latlng.rb +38 -0
  41. metadata +109 -13
@@ -0,0 +1,281 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Copyright 2024 Google LLC
4
+ #
5
+ # Licensed under the Apache License, Version 2.0 (the "License");
6
+ # you may not use this file except in compliance with the License.
7
+ # You may obtain a copy of the License at
8
+ #
9
+ # https://www.apache.org/licenses/LICENSE-2.0
10
+ #
11
+ # Unless required by applicable law or agreed to in writing, software
12
+ # distributed under the License is distributed on an "AS IS" BASIS,
13
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ # See the License for the specific language governing permissions and
15
+ # limitations under the License.
16
+
17
+ # Auto-generated by gapic-generator-ruby. DO NOT EDIT!
18
+
19
+
20
+ module Google
21
+ module Maps
22
+ module FleetEngine
23
+ module Delivery
24
+ module V1
25
+ # A Task in the Delivery API represents a single action to track. In general,
26
+ # there is a distinction between shipment-related Tasks and break Tasks. A
27
+ # shipment can have multiple Tasks associated with it. For example, there could
28
+ # be one Task for the pickup, and one for the drop-off or transfer. Also,
29
+ # different Tasks for a given shipment can be handled by different vehicles.
30
+ # For example, one vehicle could handle the pickup, driving the shipment to the
31
+ # hub, while another vehicle drives the same shipment from the hub to the
32
+ # drop-off location.
33
+ #
34
+ # Note: gRPC and REST APIs use different field naming conventions. For example,
35
+ # the `Task.journey_sharing_info` field in the gRPC API and the
36
+ # `Task.journeySharingInfo` field in the REST API refer to the same
37
+ # field.
38
+ # @!attribute [rw] name
39
+ # @return [::String]
40
+ # Must be in the format `providers/{provider}/tasks/{task}`.
41
+ # @!attribute [rw] type
42
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::Task::Type]
43
+ # Required. Immutable. Defines the type of the Task. For example, a break or
44
+ # shipment.
45
+ # @!attribute [rw] state
46
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::Task::State]
47
+ # Required. The current execution state of the Task.
48
+ # @!attribute [rw] task_outcome
49
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::Task::TaskOutcome]
50
+ # The outcome of the Task.
51
+ # @!attribute [rw] task_outcome_time
52
+ # @return [::Google::Protobuf::Timestamp]
53
+ # The timestamp that indicates when the `Task`'s outcome was set by the
54
+ # provider.
55
+ # @!attribute [rw] task_outcome_location
56
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::LocationInfo]
57
+ # The location where the `Task`'s outcome was set. This value is updated as
58
+ # part of `UpdateTask`. If this value isn't explicitly updated by the
59
+ # provider, then Fleet Engine populates it by default with the last known
60
+ # vehicle location (the *raw* location).
61
+ # @!attribute [rw] task_outcome_location_source
62
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::Task::TaskOutcomeLocationSource]
63
+ # Indicates where the value of the `task_outcome_location` came from.
64
+ # @!attribute [rw] tracking_id
65
+ # @return [::String]
66
+ # Immutable. This field facilitates the storing of an ID so you can avoid
67
+ # using a complicated mapping. You cannot set `tracking_id` for Tasks of type
68
+ # `UNAVAILABLE` and `SCHEDULED_STOP`. These IDs are subject to the
69
+ # following restrictions:
70
+ #
71
+ # * Must be a valid Unicode string.
72
+ # * Limited to a maximum length of 64 characters.
73
+ # * Normalized according to [Unicode Normalization Form C]
74
+ # (http://www.unicode.org/reports/tr15/).
75
+ # * May not contain any of the following ASCII characters: '/', ':', '?',
76
+ # ',', or '#'.
77
+ # @!attribute [r] delivery_vehicle_id
78
+ # @return [::String]
79
+ # Output only. The ID of the vehicle that is executing this Task. Delivery
80
+ # Vehicle IDs are subject to the following restrictions:
81
+ #
82
+ # * Must be a valid Unicode string.
83
+ # * Limited to a maximum length of 64 characters.
84
+ # * Normalized according to [Unicode Normalization Form C]
85
+ # (http://www.unicode.org/reports/tr15/).
86
+ # * May not contain any of the following ASCII characters: '/', ':', '?',
87
+ # ',', or '#'.
88
+ # @!attribute [rw] planned_location
89
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::LocationInfo]
90
+ # Immutable. The location where the Task will be completed.
91
+ # Optional for `UNAVAILABLE` Tasks, but required for all other Tasks.
92
+ # @!attribute [rw] task_duration
93
+ # @return [::Google::Protobuf::Duration]
94
+ # Required. Immutable. The time needed to execute a Task at this location.
95
+ # @!attribute [rw] target_time_window
96
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::TimeWindow]
97
+ # The time window during which the task should be completed.
98
+ # @!attribute [r] journey_sharing_info
99
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::Task::JourneySharingInfo]
100
+ # Output only. Journey sharing-specific fields. Not populated when state is
101
+ # `CLOSED`.
102
+ # @!attribute [rw] task_tracking_view_config
103
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::TaskTrackingViewConfig]
104
+ # The configuration for task tracking that specifies which data elements are
105
+ # visible to the end users under what circumstances.
106
+ # @!attribute [rw] attributes
107
+ # @return [::Array<::Google::Maps::FleetEngine::Delivery::V1::TaskAttribute>]
108
+ # A list of custom Task attributes. Each attribute must have a unique key.
109
+ class Task
110
+ include ::Google::Protobuf::MessageExts
111
+ extend ::Google::Protobuf::MessageExts::ClassMethods
112
+
113
+ # Journey sharing specific fields.
114
+ # @!attribute [rw] remaining_vehicle_journey_segments
115
+ # @return [::Array<::Google::Maps::FleetEngine::Delivery::V1::VehicleJourneySegment>]
116
+ # Tracking information for the stops that the assigned vehicle will make
117
+ # before it completes this Task. Note that this list can contain stops
118
+ # from other tasks.
119
+ #
120
+ # The first segment,
121
+ # `Task.journey_sharing_info.remaining_vehicle_journey_segments[0]` (gRPC)
122
+ # or `Task.journeySharingInfo.remainingVehicleJourneySegments[0]` (REST),
123
+ # contains route information from the driver's last known location to the
124
+ # upcoming `VehicleStop`. Current route information usually comes from the
125
+ # driver app, except for some cases noted in the documentation for
126
+ # {::Google::Maps::FleetEngine::Delivery::V1::DeliveryVehicle#current_route_segment DeliveryVehicle.current_route_segment}.
127
+ # The other segments in
128
+ # `Task.journey_sharing_info.remaining_vehicle_journey_segments` (gRPC) or
129
+ # `Task.journeySharingInfo.remainingVehicleJourneySegments` (REST) are
130
+ # populated by Fleet Engine. They provide route information between the
131
+ # remaining `VehicleStops`.
132
+ # @!attribute [rw] last_location
133
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::DeliveryVehicleLocation]
134
+ # Indicates the vehicle's last reported location of the assigned vehicle.
135
+ # @!attribute [rw] last_location_snappable
136
+ # @return [::Boolean]
137
+ # Indicates whether the vehicle's lastLocation can be snapped to
138
+ # the `current_route_segment`. This value is False if either
139
+ # `last_location` or `current_route_segment` don't exist. This value is
140
+ # computed by Fleet Engine. Updates from clients are ignored.
141
+ class JourneySharingInfo
142
+ include ::Google::Protobuf::MessageExts
143
+ extend ::Google::Protobuf::MessageExts::ClassMethods
144
+ end
145
+
146
+ # The type of Task.
147
+ module Type
148
+ # Default, the Task type is unknown.
149
+ TYPE_UNSPECIFIED = 0
150
+
151
+ # A pickup Task is the action taken for picking up a shipment from a
152
+ # customer. Depot or feeder vehicle pickups should use the `SCHEDULED_STOP`
153
+ # type.
154
+ PICKUP = 1
155
+
156
+ # A delivery Task is the action taken for delivering a shipment to an end
157
+ # customer. Depot or feeder vehicle dropoffs should use the
158
+ # `SCHEDULED_STOP` type.
159
+ DELIVERY = 2
160
+
161
+ # A scheduled stop Task is used for planning purposes. For example, it
162
+ # could represent picking up or dropping off shipments from feeder vehicles
163
+ # or depots. It shouldn't be used for any shipments that are picked up or
164
+ # dropped off from an end customer.
165
+ SCHEDULED_STOP = 3
166
+
167
+ # A Task that means the Vehicle is not available for service. For example,
168
+ # this can happen when the driver takes a break, or when the vehicle
169
+ # is being refueled.
170
+ UNAVAILABLE = 4
171
+ end
172
+
173
+ # The state of a Task. This indicates the Tasks's progress.
174
+ module State
175
+ # Default. Used for an unspecified or unrecognized Task state.
176
+ STATE_UNSPECIFIED = 0
177
+
178
+ # Either the Task has not yet been assigned to a delivery vehicle, or the
179
+ # delivery vehicle has not yet passed the `Task`'s assigned vehicle stop.
180
+ OPEN = 1
181
+
182
+ # When the vehicle passes the vehicle stop for this Task.
183
+ CLOSED = 2
184
+ end
185
+
186
+ # The outcome of attempting to execute a Task. When `TaskState` is closed,
187
+ # `TaskOutcome` indicates whether it was completed successfully.
188
+ module TaskOutcome
189
+ # The Task outcome before its value is set.
190
+ TASK_OUTCOME_UNSPECIFIED = 0
191
+
192
+ # The Task completed successfully.
193
+ SUCCEEDED = 1
194
+
195
+ # Either the Task couldn't be completed, or it was cancelled.
196
+ FAILED = 2
197
+ end
198
+
199
+ # The identity of the source that populated the `task_outcome_location`.
200
+ module TaskOutcomeLocationSource
201
+ # The task outcome before it is set.
202
+ TASK_OUTCOME_LOCATION_SOURCE_UNSPECIFIED = 0
203
+
204
+ # The provider-specified the `task_outcome_location`.
205
+ PROVIDER = 2
206
+
207
+ # The provider didn't specify the `task_outcome_location`, so Fleet Engine
208
+ # used the last known vehicle location.
209
+ LAST_VEHICLE_LOCATION = 3
210
+ end
211
+ end
212
+
213
+ # The configuration message that defines when a data element of a Task should
214
+ # be visible to the end users.
215
+ # @!attribute [rw] route_polyline_points_visibility
216
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::TaskTrackingViewConfig::VisibilityOption]
217
+ # The field that specifies when route polyline points can be visible. If this
218
+ # field is not specified, the project level default visibility configuration
219
+ # for this data will be used.
220
+ # @!attribute [rw] estimated_arrival_time_visibility
221
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::TaskTrackingViewConfig::VisibilityOption]
222
+ # The field that specifies when estimated arrival time can be visible. If
223
+ # this field is not specified, the project level default visibility
224
+ # configuration for this data will be used.
225
+ # @!attribute [rw] estimated_task_completion_time_visibility
226
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::TaskTrackingViewConfig::VisibilityOption]
227
+ # The field that specifies when estimated task completion time can be
228
+ # visible. If this field is not specified, the project level default
229
+ # visibility configuration for this data will be used.
230
+ # @!attribute [rw] remaining_driving_distance_visibility
231
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::TaskTrackingViewConfig::VisibilityOption]
232
+ # The field that specifies when remaining driving distance can be visible. If
233
+ # this field is not specified, the project level default visibility
234
+ # configuration for this data will be used.
235
+ # @!attribute [rw] remaining_stop_count_visibility
236
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::TaskTrackingViewConfig::VisibilityOption]
237
+ # The field that specifies when remaining stop count can be visible. If this
238
+ # field is not specified, the project level default visibility configuration
239
+ # for this data will be used.
240
+ # @!attribute [rw] vehicle_location_visibility
241
+ # @return [::Google::Maps::FleetEngine::Delivery::V1::TaskTrackingViewConfig::VisibilityOption]
242
+ # The field that specifies when vehicle location can be visible. If this
243
+ # field is not specified, the project level default visibility configuration
244
+ # for this data will be used.
245
+ class TaskTrackingViewConfig
246
+ include ::Google::Protobuf::MessageExts
247
+ extend ::Google::Protobuf::MessageExts::ClassMethods
248
+
249
+ # The option message that defines when a data element should be visible to
250
+ # the end users.
251
+ # @!attribute [rw] remaining_stop_count_threshold
252
+ # @return [::Integer]
253
+ # This data element is visible to the end users if the remaining stop
254
+ # count <= remaining_stop_count_threshold.
255
+ # @!attribute [rw] duration_until_estimated_arrival_time_threshold
256
+ # @return [::Google::Protobuf::Duration]
257
+ # This data element is visible to the end users if the ETA to the stop
258
+ # <= duration_until_estimated_arrival_time_threshold.
259
+ # @!attribute [rw] remaining_driving_distance_meters_threshold
260
+ # @return [::Integer]
261
+ # This data element is visible to the end users if the remaining
262
+ # driving distance in meters <=
263
+ # remaining_driving_distance_meters_threshold.
264
+ # @!attribute [rw] always
265
+ # @return [::Boolean]
266
+ # If set to true, this data element is always visible to the end users
267
+ # with no thresholds. This field cannot be set to false.
268
+ # @!attribute [rw] never
269
+ # @return [::Boolean]
270
+ # If set to true, this data element is always hidden from the end users
271
+ # with no thresholds. This field cannot be set to false.
272
+ class VisibilityOption
273
+ include ::Google::Protobuf::MessageExts
274
+ extend ::Google::Protobuf::MessageExts::ClassMethods
275
+ end
276
+ end
277
+ end
278
+ end
279
+ end
280
+ end
281
+ end
@@ -0,0 +1,98 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Copyright 2024 Google LLC
4
+ #
5
+ # Licensed under the Apache License, Version 2.0 (the "License");
6
+ # you may not use this file except in compliance with the License.
7
+ # You may obtain a copy of the License at
8
+ #
9
+ # https://www.apache.org/licenses/LICENSE-2.0
10
+ #
11
+ # Unless required by applicable law or agreed to in writing, software
12
+ # distributed under the License is distributed on an "AS IS" BASIS,
13
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ # See the License for the specific language governing permissions and
15
+ # limitations under the License.
16
+
17
+ # Auto-generated by gapic-generator-ruby. DO NOT EDIT!
18
+
19
+
20
+ module Google
21
+ module Protobuf
22
+ # A Duration represents a signed, fixed-length span of time represented
23
+ # as a count of seconds and fractions of seconds at nanosecond
24
+ # resolution. It is independent of any calendar and concepts like "day"
25
+ # or "month". It is related to Timestamp in that the difference between
26
+ # two Timestamp values is a Duration and it can be added or subtracted
27
+ # from a Timestamp. Range is approximately +-10,000 years.
28
+ #
29
+ # # Examples
30
+ #
31
+ # Example 1: Compute Duration from two Timestamps in pseudo code.
32
+ #
33
+ # Timestamp start = ...;
34
+ # Timestamp end = ...;
35
+ # Duration duration = ...;
36
+ #
37
+ # duration.seconds = end.seconds - start.seconds;
38
+ # duration.nanos = end.nanos - start.nanos;
39
+ #
40
+ # if (duration.seconds < 0 && duration.nanos > 0) {
41
+ # duration.seconds += 1;
42
+ # duration.nanos -= 1000000000;
43
+ # } else if (duration.seconds > 0 && duration.nanos < 0) {
44
+ # duration.seconds -= 1;
45
+ # duration.nanos += 1000000000;
46
+ # }
47
+ #
48
+ # Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.
49
+ #
50
+ # Timestamp start = ...;
51
+ # Duration duration = ...;
52
+ # Timestamp end = ...;
53
+ #
54
+ # end.seconds = start.seconds + duration.seconds;
55
+ # end.nanos = start.nanos + duration.nanos;
56
+ #
57
+ # if (end.nanos < 0) {
58
+ # end.seconds -= 1;
59
+ # end.nanos += 1000000000;
60
+ # } else if (end.nanos >= 1000000000) {
61
+ # end.seconds += 1;
62
+ # end.nanos -= 1000000000;
63
+ # }
64
+ #
65
+ # Example 3: Compute Duration from datetime.timedelta in Python.
66
+ #
67
+ # td = datetime.timedelta(days=3, minutes=10)
68
+ # duration = Duration()
69
+ # duration.FromTimedelta(td)
70
+ #
71
+ # # JSON Mapping
72
+ #
73
+ # In JSON format, the Duration type is encoded as a string rather than an
74
+ # object, where the string ends in the suffix "s" (indicating seconds) and
75
+ # is preceded by the number of seconds, with nanoseconds expressed as
76
+ # fractional seconds. For example, 3 seconds with 0 nanoseconds should be
77
+ # encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should
78
+ # be expressed in JSON format as "3.000000001s", and 3 seconds and 1
79
+ # microsecond should be expressed in JSON format as "3.000001s".
80
+ # @!attribute [rw] seconds
81
+ # @return [::Integer]
82
+ # Signed seconds of the span of time. Must be from -315,576,000,000
83
+ # to +315,576,000,000 inclusive. Note: these bounds are computed from:
84
+ # 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years
85
+ # @!attribute [rw] nanos
86
+ # @return [::Integer]
87
+ # Signed fractions of a second at nanosecond resolution of the span
88
+ # of time. Durations less than one second are represented with a 0
89
+ # `seconds` field and a positive or negative `nanos` field. For durations
90
+ # of one second or more, a non-zero value for the `nanos` field must be
91
+ # of the same sign as the `seconds` field. Must be from -999,999,999
92
+ # to +999,999,999 inclusive.
93
+ class Duration
94
+ include ::Google::Protobuf::MessageExts
95
+ extend ::Google::Protobuf::MessageExts::ClassMethods
96
+ end
97
+ end
98
+ end
@@ -0,0 +1,229 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Copyright 2024 Google LLC
4
+ #
5
+ # Licensed under the Apache License, Version 2.0 (the "License");
6
+ # you may not use this file except in compliance with the License.
7
+ # You may obtain a copy of the License at
8
+ #
9
+ # https://www.apache.org/licenses/LICENSE-2.0
10
+ #
11
+ # Unless required by applicable law or agreed to in writing, software
12
+ # distributed under the License is distributed on an "AS IS" BASIS,
13
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ # See the License for the specific language governing permissions and
15
+ # limitations under the License.
16
+
17
+ # Auto-generated by gapic-generator-ruby. DO NOT EDIT!
18
+
19
+
20
+ module Google
21
+ module Protobuf
22
+ # `FieldMask` represents a set of symbolic field paths, for example:
23
+ #
24
+ # paths: "f.a"
25
+ # paths: "f.b.d"
26
+ #
27
+ # Here `f` represents a field in some root message, `a` and `b`
28
+ # fields in the message found in `f`, and `d` a field found in the
29
+ # message in `f.b`.
30
+ #
31
+ # Field masks are used to specify a subset of fields that should be
32
+ # returned by a get operation or modified by an update operation.
33
+ # Field masks also have a custom JSON encoding (see below).
34
+ #
35
+ # # Field Masks in Projections
36
+ #
37
+ # When used in the context of a projection, a response message or
38
+ # sub-message is filtered by the API to only contain those fields as
39
+ # specified in the mask. For example, if the mask in the previous
40
+ # example is applied to a response message as follows:
41
+ #
42
+ # f {
43
+ # a : 22
44
+ # b {
45
+ # d : 1
46
+ # x : 2
47
+ # }
48
+ # y : 13
49
+ # }
50
+ # z: 8
51
+ #
52
+ # The result will not contain specific values for fields x,y and z
53
+ # (their value will be set to the default, and omitted in proto text
54
+ # output):
55
+ #
56
+ #
57
+ # f {
58
+ # a : 22
59
+ # b {
60
+ # d : 1
61
+ # }
62
+ # }
63
+ #
64
+ # A repeated field is not allowed except at the last position of a
65
+ # paths string.
66
+ #
67
+ # If a FieldMask object is not present in a get operation, the
68
+ # operation applies to all fields (as if a FieldMask of all fields
69
+ # had been specified).
70
+ #
71
+ # Note that a field mask does not necessarily apply to the
72
+ # top-level response message. In case of a REST get operation, the
73
+ # field mask applies directly to the response, but in case of a REST
74
+ # list operation, the mask instead applies to each individual message
75
+ # in the returned resource list. In case of a REST custom method,
76
+ # other definitions may be used. Where the mask applies will be
77
+ # clearly documented together with its declaration in the API. In
78
+ # any case, the effect on the returned resource/resources is required
79
+ # behavior for APIs.
80
+ #
81
+ # # Field Masks in Update Operations
82
+ #
83
+ # A field mask in update operations specifies which fields of the
84
+ # targeted resource are going to be updated. The API is required
85
+ # to only change the values of the fields as specified in the mask
86
+ # and leave the others untouched. If a resource is passed in to
87
+ # describe the updated values, the API ignores the values of all
88
+ # fields not covered by the mask.
89
+ #
90
+ # If a repeated field is specified for an update operation, new values will
91
+ # be appended to the existing repeated field in the target resource. Note that
92
+ # a repeated field is only allowed in the last position of a `paths` string.
93
+ #
94
+ # If a sub-message is specified in the last position of the field mask for an
95
+ # update operation, then new value will be merged into the existing sub-message
96
+ # in the target resource.
97
+ #
98
+ # For example, given the target message:
99
+ #
100
+ # f {
101
+ # b {
102
+ # d: 1
103
+ # x: 2
104
+ # }
105
+ # c: [1]
106
+ # }
107
+ #
108
+ # And an update message:
109
+ #
110
+ # f {
111
+ # b {
112
+ # d: 10
113
+ # }
114
+ # c: [2]
115
+ # }
116
+ #
117
+ # then if the field mask is:
118
+ #
119
+ # paths: ["f.b", "f.c"]
120
+ #
121
+ # then the result will be:
122
+ #
123
+ # f {
124
+ # b {
125
+ # d: 10
126
+ # x: 2
127
+ # }
128
+ # c: [1, 2]
129
+ # }
130
+ #
131
+ # An implementation may provide options to override this default behavior for
132
+ # repeated and message fields.
133
+ #
134
+ # In order to reset a field's value to the default, the field must
135
+ # be in the mask and set to the default value in the provided resource.
136
+ # Hence, in order to reset all fields of a resource, provide a default
137
+ # instance of the resource and set all fields in the mask, or do
138
+ # not provide a mask as described below.
139
+ #
140
+ # If a field mask is not present on update, the operation applies to
141
+ # all fields (as if a field mask of all fields has been specified).
142
+ # Note that in the presence of schema evolution, this may mean that
143
+ # fields the client does not know and has therefore not filled into
144
+ # the request will be reset to their default. If this is unwanted
145
+ # behavior, a specific service may require a client to always specify
146
+ # a field mask, producing an error if not.
147
+ #
148
+ # As with get operations, the location of the resource which
149
+ # describes the updated values in the request message depends on the
150
+ # operation kind. In any case, the effect of the field mask is
151
+ # required to be honored by the API.
152
+ #
153
+ # ## Considerations for HTTP REST
154
+ #
155
+ # The HTTP kind of an update operation which uses a field mask must
156
+ # be set to PATCH instead of PUT in order to satisfy HTTP semantics
157
+ # (PUT must only be used for full updates).
158
+ #
159
+ # # JSON Encoding of Field Masks
160
+ #
161
+ # In JSON, a field mask is encoded as a single string where paths are
162
+ # separated by a comma. Fields name in each path are converted
163
+ # to/from lower-camel naming conventions.
164
+ #
165
+ # As an example, consider the following message declarations:
166
+ #
167
+ # message Profile {
168
+ # User user = 1;
169
+ # Photo photo = 2;
170
+ # }
171
+ # message User {
172
+ # string display_name = 1;
173
+ # string address = 2;
174
+ # }
175
+ #
176
+ # In proto a field mask for `Profile` may look as such:
177
+ #
178
+ # mask {
179
+ # paths: "user.display_name"
180
+ # paths: "photo"
181
+ # }
182
+ #
183
+ # In JSON, the same mask is represented as below:
184
+ #
185
+ # {
186
+ # mask: "user.displayName,photo"
187
+ # }
188
+ #
189
+ # # Field Masks and Oneof Fields
190
+ #
191
+ # Field masks treat fields in oneofs just as regular fields. Consider the
192
+ # following message:
193
+ #
194
+ # message SampleMessage {
195
+ # oneof test_oneof {
196
+ # string name = 4;
197
+ # SubMessage sub_message = 9;
198
+ # }
199
+ # }
200
+ #
201
+ # The field mask can be:
202
+ #
203
+ # mask {
204
+ # paths: "name"
205
+ # }
206
+ #
207
+ # Or:
208
+ #
209
+ # mask {
210
+ # paths: "sub_message"
211
+ # }
212
+ #
213
+ # Note that oneof type names ("test_oneof" in this case) cannot be used in
214
+ # paths.
215
+ #
216
+ # ## Field Mask Verification
217
+ #
218
+ # The implementation of any API method which has a FieldMask type field in the
219
+ # request should verify the included field paths, and return an
220
+ # `INVALID_ARGUMENT` error if any path is unmappable.
221
+ # @!attribute [rw] paths
222
+ # @return [::Array<::String>]
223
+ # The set of field mask paths.
224
+ class FieldMask
225
+ include ::Google::Protobuf::MessageExts
226
+ extend ::Google::Protobuf::MessageExts::ClassMethods
227
+ end
228
+ end
229
+ end