google-iam-v1 0.1.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.
- checksums.yaml +7 -0
- data/.yardopts +11 -0
- data/LICENSE.md +201 -0
- data/README.md +15 -0
- data/lib/google/iam/v1/iam_policy/client.rb +625 -0
- data/lib/google/iam/v1/iam_policy/credentials.rb +42 -0
- data/lib/google/iam/v1/iam_policy.rb +71 -0
- data/lib/google/iam/v1/iam_policy_pb.rb +44 -0
- data/lib/google/iam/v1/iam_policy_services_pb.rb +83 -0
- data/lib/google/iam/v1/logging/audit_data_pb.rb +25 -0
- data/lib/google/iam/v1/options_pb.rb +20 -0
- data/lib/google/iam/v1/policy_pb.rb +79 -0
- data/lib/google/iam/v1/version.rb +26 -0
- data/lib/google/iam/v1.rb +38 -0
- data/lib/google-iam-v1.rb +21 -0
- data/proto_docs/README.md +4 -0
- data/proto_docs/google/api/field_behavior.rb +71 -0
- data/proto_docs/google/api/resource.rb +222 -0
- data/proto_docs/google/iam/v1/iam_policy.rb +87 -0
- data/proto_docs/google/iam/v1/options.rb +50 -0
- data/proto_docs/google/iam/v1/policy.rb +418 -0
- data/proto_docs/google/protobuf/field_mask.rb +229 -0
- data/proto_docs/google/type/expr.rb +75 -0
- metadata +227 -0
@@ -0,0 +1,418 @@
|
|
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 Iam
|
22
|
+
module V1
|
23
|
+
# An Identity and Access Management (IAM) policy, which specifies access
|
24
|
+
# controls for Google Cloud resources.
|
25
|
+
#
|
26
|
+
#
|
27
|
+
# A `Policy` is a collection of `bindings`. A `binding` binds one or more
|
28
|
+
# `members`, or principals, to a single `role`. Principals can be user
|
29
|
+
# accounts, service accounts, Google groups, and domains (such as G Suite). A
|
30
|
+
# `role` is a named list of permissions; each `role` can be an IAM predefined
|
31
|
+
# role or a user-created custom role.
|
32
|
+
#
|
33
|
+
# For some types of Google Cloud resources, a `binding` can also specify a
|
34
|
+
# `condition`, which is a logical expression that allows access to a resource
|
35
|
+
# only if the expression evaluates to `true`. A condition can add constraints
|
36
|
+
# based on attributes of the request, the resource, or both. To learn which
|
37
|
+
# resources support conditions in their IAM policies, see the
|
38
|
+
# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
|
39
|
+
#
|
40
|
+
# **JSON example:**
|
41
|
+
#
|
42
|
+
# {
|
43
|
+
# "bindings": [
|
44
|
+
# {
|
45
|
+
# "role": "roles/resourcemanager.organizationAdmin",
|
46
|
+
# "members": [
|
47
|
+
# "user:mike@example.com",
|
48
|
+
# "group:admins@example.com",
|
49
|
+
# "domain:google.com",
|
50
|
+
# "serviceAccount:my-project-id@appspot.gserviceaccount.com"
|
51
|
+
# ]
|
52
|
+
# },
|
53
|
+
# {
|
54
|
+
# "role": "roles/resourcemanager.organizationViewer",
|
55
|
+
# "members": [
|
56
|
+
# "user:eve@example.com"
|
57
|
+
# ],
|
58
|
+
# "condition": {
|
59
|
+
# "title": "expirable access",
|
60
|
+
# "description": "Does not grant access after Sep 2020",
|
61
|
+
# "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",
|
62
|
+
# }
|
63
|
+
# }
|
64
|
+
# ],
|
65
|
+
# "etag": "BwWWja0YfJA=",
|
66
|
+
# "version": 3
|
67
|
+
# }
|
68
|
+
#
|
69
|
+
# **YAML example:**
|
70
|
+
#
|
71
|
+
# bindings:
|
72
|
+
# - members:
|
73
|
+
# - user:mike@example.com
|
74
|
+
# - group:admins@example.com
|
75
|
+
# - domain:google.com
|
76
|
+
# - serviceAccount:my-project-id@appspot.gserviceaccount.com
|
77
|
+
# role: roles/resourcemanager.organizationAdmin
|
78
|
+
# - members:
|
79
|
+
# - user:eve@example.com
|
80
|
+
# role: roles/resourcemanager.organizationViewer
|
81
|
+
# condition:
|
82
|
+
# title: expirable access
|
83
|
+
# description: Does not grant access after Sep 2020
|
84
|
+
# expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
|
85
|
+
# etag: BwWWja0YfJA=
|
86
|
+
# version: 3
|
87
|
+
#
|
88
|
+
# For a description of IAM and its features, see the
|
89
|
+
# [IAM documentation](https://cloud.google.com/iam/docs/).
|
90
|
+
# @!attribute [rw] version
|
91
|
+
# @return [::Integer]
|
92
|
+
# Specifies the format of the policy.
|
93
|
+
#
|
94
|
+
# Valid values are `0`, `1`, and `3`. Requests that specify an invalid value
|
95
|
+
# are rejected.
|
96
|
+
#
|
97
|
+
# Any operation that affects conditional role bindings must specify version
|
98
|
+
# `3`. This requirement applies to the following operations:
|
99
|
+
#
|
100
|
+
# * Getting a policy that includes a conditional role binding
|
101
|
+
# * Adding a conditional role binding to a policy
|
102
|
+
# * Changing a conditional role binding in a policy
|
103
|
+
# * Removing any role binding, with or without a condition, from a policy
|
104
|
+
# that includes conditions
|
105
|
+
#
|
106
|
+
# **Important:** If you use IAM Conditions, you must include the `etag` field
|
107
|
+
# whenever you call `setIamPolicy`. If you omit this field, then IAM allows
|
108
|
+
# you to overwrite a version `3` policy with a version `1` policy, and all of
|
109
|
+
# the conditions in the version `3` policy are lost.
|
110
|
+
#
|
111
|
+
# If a policy does not include any conditions, operations on that policy may
|
112
|
+
# specify any valid version or leave the field unset.
|
113
|
+
#
|
114
|
+
# To learn which resources support conditions in their IAM policies, see the
|
115
|
+
# [IAM documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
|
116
|
+
# @!attribute [rw] bindings
|
117
|
+
# @return [::Array<::Google::Iam::V1::Binding>]
|
118
|
+
# Associates a list of `members`, or principals, with a `role`. Optionally,
|
119
|
+
# may specify a `condition` that determines how and when the `bindings` are
|
120
|
+
# applied. Each of the `bindings` must contain at least one principal.
|
121
|
+
#
|
122
|
+
# The `bindings` in a `Policy` can refer to up to 1,500 principals; up to 250
|
123
|
+
# of these principals can be Google groups. Each occurrence of a principal
|
124
|
+
# counts towards these limits. For example, if the `bindings` grant 50
|
125
|
+
# different roles to `user:alice@example.com`, and not to any other
|
126
|
+
# principal, then you can add another 1,450 principals to the `bindings` in
|
127
|
+
# the `Policy`.
|
128
|
+
# @!attribute [rw] audit_configs
|
129
|
+
# @return [::Array<::Google::Iam::V1::AuditConfig>]
|
130
|
+
# Specifies cloud audit logging configuration for this policy.
|
131
|
+
# @!attribute [rw] etag
|
132
|
+
# @return [::String]
|
133
|
+
# `etag` is used for optimistic concurrency control as a way to help
|
134
|
+
# prevent simultaneous updates of a policy from overwriting each other.
|
135
|
+
# It is strongly suggested that systems make use of the `etag` in the
|
136
|
+
# read-modify-write cycle to perform policy updates in order to avoid race
|
137
|
+
# conditions: An `etag` is returned in the response to `getIamPolicy`, and
|
138
|
+
# systems are expected to put that etag in the request to `setIamPolicy` to
|
139
|
+
# ensure that their change will be applied to the same version of the policy.
|
140
|
+
#
|
141
|
+
# **Important:** If you use IAM Conditions, you must include the `etag` field
|
142
|
+
# whenever you call `setIamPolicy`. If you omit this field, then IAM allows
|
143
|
+
# you to overwrite a version `3` policy with a version `1` policy, and all of
|
144
|
+
# the conditions in the version `3` policy are lost.
|
145
|
+
class Policy
|
146
|
+
include ::Google::Protobuf::MessageExts
|
147
|
+
extend ::Google::Protobuf::MessageExts::ClassMethods
|
148
|
+
end
|
149
|
+
|
150
|
+
# Associates `members`, or principals, with a `role`.
|
151
|
+
# @!attribute [rw] role
|
152
|
+
# @return [::String]
|
153
|
+
# Role that is assigned to the list of `members`, or principals.
|
154
|
+
# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
|
155
|
+
# @!attribute [rw] members
|
156
|
+
# @return [::Array<::String>]
|
157
|
+
# Specifies the principals requesting access for a Cloud Platform resource.
|
158
|
+
# `members` can have the following values:
|
159
|
+
#
|
160
|
+
# * `allUsers`: A special identifier that represents anyone who is
|
161
|
+
# on the internet; with or without a Google account.
|
162
|
+
#
|
163
|
+
# * `allAuthenticatedUsers`: A special identifier that represents anyone
|
164
|
+
# who is authenticated with a Google account or a service account.
|
165
|
+
#
|
166
|
+
# * `user:{emailid}`: An email address that represents a specific Google
|
167
|
+
# account. For example, `alice@example.com` .
|
168
|
+
#
|
169
|
+
#
|
170
|
+
# * `serviceAccount:{emailid}`: An email address that represents a service
|
171
|
+
# account. For example, `my-other-app@appspot.gserviceaccount.com`.
|
172
|
+
#
|
173
|
+
# * `group:{emailid}`: An email address that represents a Google group.
|
174
|
+
# For example, `admins@example.com`.
|
175
|
+
#
|
176
|
+
# * `deleted:user:{emailid}?uid={uniqueid}`: An email address (plus unique
|
177
|
+
# identifier) representing a user that has been recently deleted. For
|
178
|
+
# example, `alice@example.com?uid=123456789012345678901`. If the user is
|
179
|
+
# recovered, this value reverts to `user:{emailid}` and the recovered user
|
180
|
+
# retains the role in the binding.
|
181
|
+
#
|
182
|
+
# * `deleted:serviceAccount:{emailid}?uid={uniqueid}`: An email address (plus
|
183
|
+
# unique identifier) representing a service account that has been recently
|
184
|
+
# deleted. For example,
|
185
|
+
# `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`.
|
186
|
+
# If the service account is undeleted, this value reverts to
|
187
|
+
# `serviceAccount:{emailid}` and the undeleted service account retains the
|
188
|
+
# role in the binding.
|
189
|
+
#
|
190
|
+
# * `deleted:group:{emailid}?uid={uniqueid}`: An email address (plus unique
|
191
|
+
# identifier) representing a Google group that has been recently
|
192
|
+
# deleted. For example, `admins@example.com?uid=123456789012345678901`. If
|
193
|
+
# the group is recovered, this value reverts to `group:{emailid}` and the
|
194
|
+
# recovered group retains the role in the binding.
|
195
|
+
#
|
196
|
+
#
|
197
|
+
# * `domain:{domain}`: The G Suite domain (primary) that represents all the
|
198
|
+
# users of that domain. For example, `google.com` or `example.com`.
|
199
|
+
# @!attribute [rw] condition
|
200
|
+
# @return [::Google::Type::Expr]
|
201
|
+
# The condition that is associated with this binding.
|
202
|
+
#
|
203
|
+
# If the condition evaluates to `true`, then this binding applies to the
|
204
|
+
# current request.
|
205
|
+
#
|
206
|
+
# If the condition evaluates to `false`, then this binding does not apply to
|
207
|
+
# the current request. However, a different role binding might grant the same
|
208
|
+
# role to one or more of the principals in this binding.
|
209
|
+
#
|
210
|
+
# To learn which resources support conditions in their IAM policies, see the
|
211
|
+
# [IAM
|
212
|
+
# documentation](https://cloud.google.com/iam/help/conditions/resource-policies).
|
213
|
+
class Binding
|
214
|
+
include ::Google::Protobuf::MessageExts
|
215
|
+
extend ::Google::Protobuf::MessageExts::ClassMethods
|
216
|
+
end
|
217
|
+
|
218
|
+
# Specifies the audit configuration for a service.
|
219
|
+
# The configuration determines which permission types are logged, and what
|
220
|
+
# identities, if any, are exempted from logging.
|
221
|
+
# An AuditConfig must have one or more AuditLogConfigs.
|
222
|
+
#
|
223
|
+
# If there are AuditConfigs for both `allServices` and a specific service,
|
224
|
+
# the union of the two AuditConfigs is used for that service: the log_types
|
225
|
+
# specified in each AuditConfig are enabled, and the exempted_members in each
|
226
|
+
# AuditLogConfig are exempted.
|
227
|
+
#
|
228
|
+
# Example Policy with multiple AuditConfigs:
|
229
|
+
#
|
230
|
+
# {
|
231
|
+
# "audit_configs": [
|
232
|
+
# {
|
233
|
+
# "service": "allServices",
|
234
|
+
# "audit_log_configs": [
|
235
|
+
# {
|
236
|
+
# "log_type": "DATA_READ",
|
237
|
+
# "exempted_members": [
|
238
|
+
# "user:jose@example.com"
|
239
|
+
# ]
|
240
|
+
# },
|
241
|
+
# {
|
242
|
+
# "log_type": "DATA_WRITE"
|
243
|
+
# },
|
244
|
+
# {
|
245
|
+
# "log_type": "ADMIN_READ"
|
246
|
+
# }
|
247
|
+
# ]
|
248
|
+
# },
|
249
|
+
# {
|
250
|
+
# "service": "sampleservice.googleapis.com",
|
251
|
+
# "audit_log_configs": [
|
252
|
+
# {
|
253
|
+
# "log_type": "DATA_READ"
|
254
|
+
# },
|
255
|
+
# {
|
256
|
+
# "log_type": "DATA_WRITE",
|
257
|
+
# "exempted_members": [
|
258
|
+
# "user:aliya@example.com"
|
259
|
+
# ]
|
260
|
+
# }
|
261
|
+
# ]
|
262
|
+
# }
|
263
|
+
# ]
|
264
|
+
# }
|
265
|
+
#
|
266
|
+
# For sampleservice, this policy enables DATA_READ, DATA_WRITE and ADMIN_READ
|
267
|
+
# logging. It also exempts jose@example.com from DATA_READ logging, and
|
268
|
+
# aliya@example.com from DATA_WRITE logging.
|
269
|
+
# @!attribute [rw] service
|
270
|
+
# @return [::String]
|
271
|
+
# Specifies a service that will be enabled for audit logging.
|
272
|
+
# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.
|
273
|
+
# `allServices` is a special value that covers all services.
|
274
|
+
# @!attribute [rw] audit_log_configs
|
275
|
+
# @return [::Array<::Google::Iam::V1::AuditLogConfig>]
|
276
|
+
# The configuration for logging of each type of permission.
|
277
|
+
class AuditConfig
|
278
|
+
include ::Google::Protobuf::MessageExts
|
279
|
+
extend ::Google::Protobuf::MessageExts::ClassMethods
|
280
|
+
end
|
281
|
+
|
282
|
+
# Provides the configuration for logging a type of permissions.
|
283
|
+
# Example:
|
284
|
+
#
|
285
|
+
# {
|
286
|
+
# "audit_log_configs": [
|
287
|
+
# {
|
288
|
+
# "log_type": "DATA_READ",
|
289
|
+
# "exempted_members": [
|
290
|
+
# "user:jose@example.com"
|
291
|
+
# ]
|
292
|
+
# },
|
293
|
+
# {
|
294
|
+
# "log_type": "DATA_WRITE"
|
295
|
+
# }
|
296
|
+
# ]
|
297
|
+
# }
|
298
|
+
#
|
299
|
+
# This enables 'DATA_READ' and 'DATA_WRITE' logging, while exempting
|
300
|
+
# jose@example.com from DATA_READ logging.
|
301
|
+
# @!attribute [rw] log_type
|
302
|
+
# @return [::Google::Iam::V1::AuditLogConfig::LogType]
|
303
|
+
# The log type that this config enables.
|
304
|
+
# @!attribute [rw] exempted_members
|
305
|
+
# @return [::Array<::String>]
|
306
|
+
# Specifies the identities that do not cause logging for this type of
|
307
|
+
# permission.
|
308
|
+
# Follows the same format of {::Google::Iam::V1::Binding#members Binding.members}.
|
309
|
+
class AuditLogConfig
|
310
|
+
include ::Google::Protobuf::MessageExts
|
311
|
+
extend ::Google::Protobuf::MessageExts::ClassMethods
|
312
|
+
|
313
|
+
# The list of valid permission types for which logging can be configured.
|
314
|
+
# Admin writes are always logged, and are not configurable.
|
315
|
+
module LogType
|
316
|
+
# Default case. Should never be this.
|
317
|
+
LOG_TYPE_UNSPECIFIED = 0
|
318
|
+
|
319
|
+
# Admin reads. Example: CloudIAM getIamPolicy
|
320
|
+
ADMIN_READ = 1
|
321
|
+
|
322
|
+
# Data writes. Example: CloudSQL Users create
|
323
|
+
DATA_WRITE = 2
|
324
|
+
|
325
|
+
# Data reads. Example: CloudSQL Users list
|
326
|
+
DATA_READ = 3
|
327
|
+
end
|
328
|
+
end
|
329
|
+
|
330
|
+
# The difference delta between two policies.
|
331
|
+
# @!attribute [rw] binding_deltas
|
332
|
+
# @return [::Array<::Google::Iam::V1::BindingDelta>]
|
333
|
+
# The delta for Bindings between two policies.
|
334
|
+
# @!attribute [rw] audit_config_deltas
|
335
|
+
# @return [::Array<::Google::Iam::V1::AuditConfigDelta>]
|
336
|
+
# The delta for AuditConfigs between two policies.
|
337
|
+
class PolicyDelta
|
338
|
+
include ::Google::Protobuf::MessageExts
|
339
|
+
extend ::Google::Protobuf::MessageExts::ClassMethods
|
340
|
+
end
|
341
|
+
|
342
|
+
# One delta entry for Binding. Each individual change (only one member in each
|
343
|
+
# entry) to a binding will be a separate entry.
|
344
|
+
# @!attribute [rw] action
|
345
|
+
# @return [::Google::Iam::V1::BindingDelta::Action]
|
346
|
+
# The action that was performed on a Binding.
|
347
|
+
# Required
|
348
|
+
# @!attribute [rw] role
|
349
|
+
# @return [::String]
|
350
|
+
# Role that is assigned to `members`.
|
351
|
+
# For example, `roles/viewer`, `roles/editor`, or `roles/owner`.
|
352
|
+
# Required
|
353
|
+
# @!attribute [rw] member
|
354
|
+
# @return [::String]
|
355
|
+
# A single identity requesting access for a Cloud Platform resource.
|
356
|
+
# Follows the same format of Binding.members.
|
357
|
+
# Required
|
358
|
+
# @!attribute [rw] condition
|
359
|
+
# @return [::Google::Type::Expr]
|
360
|
+
# The condition that is associated with this binding.
|
361
|
+
class BindingDelta
|
362
|
+
include ::Google::Protobuf::MessageExts
|
363
|
+
extend ::Google::Protobuf::MessageExts::ClassMethods
|
364
|
+
|
365
|
+
# The type of action performed on a Binding in a policy.
|
366
|
+
module Action
|
367
|
+
# Unspecified.
|
368
|
+
ACTION_UNSPECIFIED = 0
|
369
|
+
|
370
|
+
# Addition of a Binding.
|
371
|
+
ADD = 1
|
372
|
+
|
373
|
+
# Removal of a Binding.
|
374
|
+
REMOVE = 2
|
375
|
+
end
|
376
|
+
end
|
377
|
+
|
378
|
+
# One delta entry for AuditConfig. Each individual change (only one
|
379
|
+
# exempted_member in each entry) to a AuditConfig will be a separate entry.
|
380
|
+
# @!attribute [rw] action
|
381
|
+
# @return [::Google::Iam::V1::AuditConfigDelta::Action]
|
382
|
+
# The action that was performed on an audit configuration in a policy.
|
383
|
+
# Required
|
384
|
+
# @!attribute [rw] service
|
385
|
+
# @return [::String]
|
386
|
+
# Specifies a service that was configured for Cloud Audit Logging.
|
387
|
+
# For example, `storage.googleapis.com`, `cloudsql.googleapis.com`.
|
388
|
+
# `allServices` is a special value that covers all services.
|
389
|
+
# Required
|
390
|
+
# @!attribute [rw] exempted_member
|
391
|
+
# @return [::String]
|
392
|
+
# A single identity that is exempted from "data access" audit
|
393
|
+
# logging for the `service` specified above.
|
394
|
+
# Follows the same format of Binding.members.
|
395
|
+
# @!attribute [rw] log_type
|
396
|
+
# @return [::String]
|
397
|
+
# Specifies the log_type that was be enabled. ADMIN_ACTIVITY is always
|
398
|
+
# enabled, and cannot be configured.
|
399
|
+
# Required
|
400
|
+
class AuditConfigDelta
|
401
|
+
include ::Google::Protobuf::MessageExts
|
402
|
+
extend ::Google::Protobuf::MessageExts::ClassMethods
|
403
|
+
|
404
|
+
# The type of action performed on an audit configuration in a policy.
|
405
|
+
module Action
|
406
|
+
# Unspecified.
|
407
|
+
ACTION_UNSPECIFIED = 0
|
408
|
+
|
409
|
+
# Addition of an audit configuration.
|
410
|
+
ADD = 1
|
411
|
+
|
412
|
+
# Removal of an audit configuration.
|
413
|
+
REMOVE = 2
|
414
|
+
end
|
415
|
+
end
|
416
|
+
end
|
417
|
+
end
|
418
|
+
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
|