google-cloud-recommender-v1 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,37 @@
1
+ # Generated by the protocol buffer compiler. DO NOT EDIT!
2
+ # source: google/cloud/recommender/v1/recommender_config.proto
3
+
4
+ require 'google/protobuf'
5
+
6
+ require 'google/api/field_behavior_pb'
7
+ require 'google/api/resource_pb'
8
+ require 'google/protobuf/struct_pb'
9
+ require 'google/protobuf/timestamp_pb'
10
+
11
+ Google::Protobuf::DescriptorPool.generated_pool.build do
12
+ add_file("google/cloud/recommender/v1/recommender_config.proto", :syntax => :proto3) do
13
+ add_message "google.cloud.recommender.v1.RecommenderConfig" do
14
+ optional :name, :string, 1
15
+ optional :recommender_generation_config, :message, 2, "google.cloud.recommender.v1.RecommenderGenerationConfig"
16
+ optional :etag, :string, 3
17
+ optional :update_time, :message, 4, "google.protobuf.Timestamp"
18
+ optional :revision_id, :string, 5
19
+ map :annotations, :string, :string, 6
20
+ optional :display_name, :string, 7
21
+ end
22
+ add_message "google.cloud.recommender.v1.RecommenderGenerationConfig" do
23
+ optional :params, :message, 1, "google.protobuf.Struct"
24
+ end
25
+ end
26
+ end
27
+
28
+ module Google
29
+ module Cloud
30
+ module Recommender
31
+ module V1
32
+ RecommenderConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.recommender.v1.RecommenderConfig").msgclass
33
+ RecommenderGenerationConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.recommender.v1.RecommenderGenerationConfig").msgclass
34
+ end
35
+ end
36
+ end
37
+ end
@@ -1,13 +1,17 @@
1
1
  # Generated by the protocol buffer compiler. DO NOT EDIT!
2
2
  # source: google/cloud/recommender/v1/recommender_service.proto
3
3
 
4
+ require 'google/protobuf'
5
+
4
6
  require 'google/api/annotations_pb'
5
7
  require 'google/api/client_pb'
6
8
  require 'google/api/field_behavior_pb'
7
9
  require 'google/api/resource_pb'
8
10
  require 'google/cloud/recommender/v1/insight_pb'
11
+ require 'google/cloud/recommender/v1/insight_type_config_pb'
9
12
  require 'google/cloud/recommender/v1/recommendation_pb'
10
- require 'google/protobuf'
13
+ require 'google/cloud/recommender/v1/recommender_config_pb'
14
+ require 'google/protobuf/field_mask_pb'
11
15
 
12
16
  Google::Protobuf::DescriptorPool.generated_pool.build do
13
17
  add_file("google/cloud/recommender/v1/recommender_service.proto", :syntax => :proto3) do
@@ -57,6 +61,22 @@ Google::Protobuf::DescriptorPool.generated_pool.build do
57
61
  map :state_metadata, :string, :string, 2
58
62
  optional :etag, :string, 3
59
63
  end
64
+ add_message "google.cloud.recommender.v1.GetRecommenderConfigRequest" do
65
+ optional :name, :string, 1
66
+ end
67
+ add_message "google.cloud.recommender.v1.UpdateRecommenderConfigRequest" do
68
+ optional :recommender_config, :message, 1, "google.cloud.recommender.v1.RecommenderConfig"
69
+ optional :update_mask, :message, 2, "google.protobuf.FieldMask"
70
+ optional :validate_only, :bool, 3
71
+ end
72
+ add_message "google.cloud.recommender.v1.GetInsightTypeConfigRequest" do
73
+ optional :name, :string, 1
74
+ end
75
+ add_message "google.cloud.recommender.v1.UpdateInsightTypeConfigRequest" do
76
+ optional :insight_type_config, :message, 1, "google.cloud.recommender.v1.InsightTypeConfig"
77
+ optional :update_mask, :message, 2, "google.protobuf.FieldMask"
78
+ optional :validate_only, :bool, 3
79
+ end
60
80
  end
61
81
  end
62
82
 
@@ -74,6 +94,10 @@ module Google
74
94
  MarkRecommendationClaimedRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.recommender.v1.MarkRecommendationClaimedRequest").msgclass
75
95
  MarkRecommendationSucceededRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.recommender.v1.MarkRecommendationSucceededRequest").msgclass
76
96
  MarkRecommendationFailedRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.recommender.v1.MarkRecommendationFailedRequest").msgclass
97
+ GetRecommenderConfigRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.recommender.v1.GetRecommenderConfigRequest").msgclass
98
+ UpdateRecommenderConfigRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.recommender.v1.UpdateRecommenderConfigRequest").msgclass
99
+ GetInsightTypeConfigRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.recommender.v1.GetInsightTypeConfigRequest").msgclass
100
+ UpdateInsightTypeConfigRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("google.cloud.recommender.v1.UpdateInsightTypeConfigRequest").msgclass
77
101
  end
78
102
  end
79
103
  end
@@ -90,6 +90,18 @@ module Google
90
90
  # Requires the recommender.*.update IAM permission for the specified
91
91
  # recommender.
92
92
  rpc :MarkRecommendationFailed, ::Google::Cloud::Recommender::V1::MarkRecommendationFailedRequest, ::Google::Cloud::Recommender::V1::Recommendation
93
+ # Gets the requested Recommender Config. There is only one instance of the
94
+ # config for each Recommender.
95
+ rpc :GetRecommenderConfig, ::Google::Cloud::Recommender::V1::GetRecommenderConfigRequest, ::Google::Cloud::Recommender::V1::RecommenderConfig
96
+ # Updates a Recommender Config. This will create a new revision of the
97
+ # config.
98
+ rpc :UpdateRecommenderConfig, ::Google::Cloud::Recommender::V1::UpdateRecommenderConfigRequest, ::Google::Cloud::Recommender::V1::RecommenderConfig
99
+ # Gets the requested InsightTypeConfig. There is only one instance of the
100
+ # config for each InsightType.
101
+ rpc :GetInsightTypeConfig, ::Google::Cloud::Recommender::V1::GetInsightTypeConfigRequest, ::Google::Cloud::Recommender::V1::InsightTypeConfig
102
+ # Updates an InsightTypeConfig change. This will create a new revision of the
103
+ # config.
104
+ rpc :UpdateInsightTypeConfig, ::Google::Cloud::Recommender::V1::UpdateInsightTypeConfigRequest, ::Google::Cloud::Recommender::V1::InsightTypeConfig
93
105
  end
94
106
 
95
107
  Stub = Service.rpc_stub_class
@@ -21,7 +21,7 @@ module Google
21
21
  module Cloud
22
22
  module Recommender
23
23
  module V1
24
- VERSION = "0.9.0"
24
+ VERSION = "0.10.0"
25
25
  end
26
26
  end
27
27
  end
@@ -0,0 +1,88 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Copyright 2022 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 Cloud
22
+ module Recommender
23
+ module V1
24
+ # Configuration for an InsightType.
25
+ # @!attribute [rw] name
26
+ # @return [::String]
27
+ # Name of insight type config.
28
+ # Eg,
29
+ # projects/[PROJECT_NUMBER]/locations/[LOCATION]/insightTypes/[INSIGHT_TYPE_ID]/config
30
+ # @!attribute [rw] insight_type_generation_config
31
+ # @return [::Google::Cloud::Recommender::V1::InsightTypeGenerationConfig]
32
+ # InsightTypeGenerationConfig which configures the generation of
33
+ # insights for this insight type.
34
+ # @!attribute [rw] etag
35
+ # @return [::String]
36
+ # Fingerprint of the InsightTypeConfig. Provides optimistic locking when
37
+ # updating.
38
+ # @!attribute [rw] update_time
39
+ # @return [::Google::Protobuf::Timestamp]
40
+ # Last time when the config was updated.
41
+ # @!attribute [r] revision_id
42
+ # @return [::String]
43
+ # Output only. Immutable. The revision ID of the config.
44
+ # A new revision is committed whenever the config is changed in any way.
45
+ # The format is an 8-character hexadecimal string.
46
+ # @!attribute [rw] annotations
47
+ # @return [::Google::Protobuf::Map{::String => ::String}]
48
+ # Allows clients to store small amounts of arbitrary data. Annotations must
49
+ # follow the Kubernetes syntax.
50
+ # The total size of all keys and values combined is limited to 256k.
51
+ # Key can have 2 segments: prefix (optional) and name (required),
52
+ # separated by a slash (/).
53
+ # Prefix must be a DNS subdomain.
54
+ # Name must be 63 characters or less, begin and end with alphanumerics,
55
+ # with dashes (-), underscores (_), dots (.), and alphanumerics between.
56
+ # @!attribute [rw] display_name
57
+ # @return [::String]
58
+ # A user-settable field to provide a human-readable name to be used in user
59
+ # interfaces.
60
+ class InsightTypeConfig
61
+ include ::Google::Protobuf::MessageExts
62
+ extend ::Google::Protobuf::MessageExts::ClassMethods
63
+
64
+ # @!attribute [rw] key
65
+ # @return [::String]
66
+ # @!attribute [rw] value
67
+ # @return [::String]
68
+ class AnnotationsEntry
69
+ include ::Google::Protobuf::MessageExts
70
+ extend ::Google::Protobuf::MessageExts::ClassMethods
71
+ end
72
+ end
73
+
74
+ # A configuration to customize the generation of insights.
75
+ # Eg, customizing the lookback period considered when generating a
76
+ # insight.
77
+ # @!attribute [rw] params
78
+ # @return [::Google::Protobuf::Struct]
79
+ # Parameters for this InsightTypeGenerationConfig. These configs can be used
80
+ # by or are applied to all subtypes.
81
+ class InsightTypeGenerationConfig
82
+ include ::Google::Protobuf::MessageExts
83
+ extend ::Google::Protobuf::MessageExts::ClassMethods
84
+ end
85
+ end
86
+ end
87
+ end
88
+ end
@@ -0,0 +1,88 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Copyright 2022 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 Cloud
22
+ module Recommender
23
+ module V1
24
+ # Configuration for a Recommender.
25
+ # @!attribute [rw] name
26
+ # @return [::String]
27
+ # Name of recommender config.
28
+ # Eg,
29
+ # projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/config
30
+ # @!attribute [rw] recommender_generation_config
31
+ # @return [::Google::Cloud::Recommender::V1::RecommenderGenerationConfig]
32
+ # RecommenderGenerationConfig which configures the Generation of
33
+ # recommendations for this recommender.
34
+ # @!attribute [rw] etag
35
+ # @return [::String]
36
+ # Fingerprint of the RecommenderConfig. Provides optimistic locking when
37
+ # updating.
38
+ # @!attribute [rw] update_time
39
+ # @return [::Google::Protobuf::Timestamp]
40
+ # Last time when the config was updated.
41
+ # @!attribute [r] revision_id
42
+ # @return [::String]
43
+ # Output only. Immutable. The revision ID of the config.
44
+ # A new revision is committed whenever the config is changed in any way.
45
+ # The format is an 8-character hexadecimal string.
46
+ # @!attribute [rw] annotations
47
+ # @return [::Google::Protobuf::Map{::String => ::String}]
48
+ # Allows clients to store small amounts of arbitrary data. Annotations must
49
+ # follow the Kubernetes syntax.
50
+ # The total size of all keys and values combined is limited to 256k.
51
+ # Key can have 2 segments: prefix (optional) and name (required),
52
+ # separated by a slash (/).
53
+ # Prefix must be a DNS subdomain.
54
+ # Name must be 63 characters or less, begin and end with alphanumerics,
55
+ # with dashes (-), underscores (_), dots (.), and alphanumerics between.
56
+ # @!attribute [rw] display_name
57
+ # @return [::String]
58
+ # A user-settable field to provide a human-readable name to be used in user
59
+ # interfaces.
60
+ class RecommenderConfig
61
+ include ::Google::Protobuf::MessageExts
62
+ extend ::Google::Protobuf::MessageExts::ClassMethods
63
+
64
+ # @!attribute [rw] key
65
+ # @return [::String]
66
+ # @!attribute [rw] value
67
+ # @return [::String]
68
+ class AnnotationsEntry
69
+ include ::Google::Protobuf::MessageExts
70
+ extend ::Google::Protobuf::MessageExts::ClassMethods
71
+ end
72
+ end
73
+
74
+ # A Configuration to customize the generation of recommendations.
75
+ # Eg, customizing the lookback period considered when generating a
76
+ # recommendation.
77
+ # @!attribute [rw] params
78
+ # @return [::Google::Protobuf::Struct]
79
+ # Parameters for this RecommenderGenerationConfig. These configs can be used
80
+ # by or are applied to all subtypes.
81
+ class RecommenderGenerationConfig
82
+ include ::Google::Protobuf::MessageExts
83
+ extend ::Google::Protobuf::MessageExts::ClassMethods
84
+ end
85
+ end
86
+ end
87
+ end
88
+ end
@@ -43,15 +43,15 @@ module Google
43
43
  # https://cloud.google.com/recommender/docs/insights/insight-types.
44
44
  # @!attribute [rw] page_size
45
45
  # @return [::Integer]
46
- # Optional. The maximum number of results to return from this request. Non-positive
47
- # values are ignored. If not specified, the server will determine the number
48
- # of results to return.
46
+ # Optional. The maximum number of results to return from this request.
47
+ # Non-positive values are ignored. If not specified, the server will
48
+ # determine the number of results to return.
49
49
  # @!attribute [rw] page_token
50
50
  # @return [::String]
51
- # Optional. If present, retrieves the next batch of results from the preceding call to
52
- # this method. `page_token` must be the value of `next_page_token` from the
53
- # previous response. The values of other method parameters must be identical
54
- # to those in the previous call.
51
+ # Optional. If present, retrieves the next batch of results from the
52
+ # preceding call to this method. `page_token` must be the value of
53
+ # `next_page_token` from the previous response. The values of other method
54
+ # parameters must be identical to those in the previous call.
55
55
  # @!attribute [rw] filter
56
56
  # @return [::String]
57
57
  # Optional. Filter expression to restrict the insights returned. Supported
@@ -108,8 +108,8 @@ module Google
108
108
  # Required. Name of the insight.
109
109
  # @!attribute [rw] state_metadata
110
110
  # @return [::Google::Protobuf::Map{::String => ::String}]
111
- # Optional. State properties user wish to include with this state. Full replace of the
112
- # current state_metadata.
111
+ # Optional. State properties user wish to include with this state. Full
112
+ # replace of the current state_metadata.
113
113
  # @!attribute [rw] etag
114
114
  # @return [::String]
115
115
  # Required. Fingerprint of the Insight. Provides optimistic locking.
@@ -149,15 +149,15 @@ module Google
149
149
  # https://cloud.google.com/recommender/docs/recommenders.
150
150
  # @!attribute [rw] page_size
151
151
  # @return [::Integer]
152
- # Optional. The maximum number of results to return from this request. Non-positive
153
- # values are ignored. If not specified, the server will determine the number
154
- # of results to return.
152
+ # Optional. The maximum number of results to return from this request.
153
+ # Non-positive values are ignored. If not specified, the server will
154
+ # determine the number of results to return.
155
155
  # @!attribute [rw] page_token
156
156
  # @return [::String]
157
- # Optional. If present, retrieves the next batch of results from the preceding call to
158
- # this method. `page_token` must be the value of `next_page_token` from the
159
- # previous response. The values of other method parameters must be identical
160
- # to those in the previous call.
157
+ # Optional. If present, retrieves the next batch of results from the
158
+ # preceding call to this method. `page_token` must be the value of
159
+ # `next_page_token` from the previous response. The values of other method
160
+ # parameters must be identical to those in the previous call.
161
161
  # @!attribute [rw] filter
162
162
  # @return [::String]
163
163
  # Filter expression to restrict the recommendations returned. Supported
@@ -288,6 +288,72 @@ module Google
288
288
  extend ::Google::Protobuf::MessageExts::ClassMethods
289
289
  end
290
290
  end
291
+
292
+ # Request for the GetRecommenderConfig` method.
293
+ # @!attribute [rw] name
294
+ # @return [::String]
295
+ # Required. Name of the Recommendation Config to get.
296
+ #
297
+ # Acceptable formats:
298
+ #
299
+ # * `projects/[PROJECT_NUMBER]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/config`
300
+ #
301
+ # * `projects/[PROJECT_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/config`
302
+ #
303
+ # * `organizations/[ORGANIZATION_ID]/locations/[LOCATION]/recommenders/[RECOMMENDER_ID]/config`
304
+ class GetRecommenderConfigRequest
305
+ include ::Google::Protobuf::MessageExts
306
+ extend ::Google::Protobuf::MessageExts::ClassMethods
307
+ end
308
+
309
+ # Request for the `UpdateRecommenderConfig` method.
310
+ # @!attribute [rw] recommender_config
311
+ # @return [::Google::Cloud::Recommender::V1::RecommenderConfig]
312
+ # Required. The RecommenderConfig to update.
313
+ # @!attribute [rw] update_mask
314
+ # @return [::Google::Protobuf::FieldMask]
315
+ # The list of fields to be updated.
316
+ # @!attribute [rw] validate_only
317
+ # @return [::Boolean]
318
+ # If true, validate the request and preview the change, but do not actually
319
+ # update it.
320
+ class UpdateRecommenderConfigRequest
321
+ include ::Google::Protobuf::MessageExts
322
+ extend ::Google::Protobuf::MessageExts::ClassMethods
323
+ end
324
+
325
+ # Request for the GetInsightTypeConfig` method.
326
+ # @!attribute [rw] name
327
+ # @return [::String]
328
+ # Required. Name of the InsightTypeConfig to get.
329
+ #
330
+ # Acceptable formats:
331
+ #
332
+ # * `projects/[PROJECT_NUMBER]/locations/global/recommenders/[INSIGHT_TYPE_ID]/config`
333
+ #
334
+ # * `projects/[PROJECT_ID]/locations/global/recommenders/[INSIGHT_TYPE_ID]/config`
335
+ #
336
+ # * `organizations/[ORGANIZATION_ID]/locations/global/recommenders/[INSIGHT_TYPE_ID]/config`
337
+ class GetInsightTypeConfigRequest
338
+ include ::Google::Protobuf::MessageExts
339
+ extend ::Google::Protobuf::MessageExts::ClassMethods
340
+ end
341
+
342
+ # Request for the `UpdateInsightTypeConfig` method.
343
+ # @!attribute [rw] insight_type_config
344
+ # @return [::Google::Cloud::Recommender::V1::InsightTypeConfig]
345
+ # Required. The InsightTypeConfig to update.
346
+ # @!attribute [rw] update_mask
347
+ # @return [::Google::Protobuf::FieldMask]
348
+ # The list of fields to be updated.
349
+ # @!attribute [rw] validate_only
350
+ # @return [::Boolean]
351
+ # If true, validate the request and preview the change, but do not actually
352
+ # update it.
353
+ class UpdateInsightTypeConfigRequest
354
+ include ::Google::Protobuf::MessageExts
355
+ extend ::Google::Protobuf::MessageExts::ClassMethods
356
+ end
291
357
  end
292
358
  end
293
359
  end
@@ -0,0 +1,229 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Copyright 2022 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
@@ -46,8 +46,8 @@ module Google
46
46
 
47
47
  # `Value` represents a dynamically typed value which can be either
48
48
  # null, a number, a string, a boolean, a recursive struct value, or a
49
- # list of values. A producer of value is expected to set one of that
50
- # variants, absence of any variant indicates an error.
49
+ # list of values. A producer of value is expected to set one of these
50
+ # variants. Absence of any variant indicates an error.
51
51
  #
52
52
  # The JSON representation for `Value` is JSON value.
53
53
  # @!attribute [rw] null_value