0
# Tag Values Management
1

2
Management of specific values within tag categories, providing the actual tags that can be applied to Google Cloud resources. TagValues represent the "value" portion of key-value tags and must be created under existing TagKeys.
3

4
## Capabilities
5

6
### Tag Value Retrieval
7

8
Retrieve detailed information about a specific TagValue using its resource name.
9

10
```python { .api }
11
def get_tag_value(
12
    self,
13
    request: GetTagValueRequest = None,
14
    *,
15
    name: str = None,
16
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
17
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
18
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
19
) -> TagValue:
20
    """
21
    Retrieves a TagValue identified by the specified resource name.
22

23
    Args:
24
        name (str): The resource name of the TagValue to retrieve.
25
            Format: tagValues/{tag_value_id}
26
        retry: Retry configuration for the request
27
        timeout: Request timeout in seconds
28
        metadata: Additional metadata to send with the request
29

30
    Returns:
31
        TagValue: The requested TagValue resource
32

33
    Raises:
34
        google.api_core.exceptions.NotFound: If the TagValue doesn't exist
35
        google.api_core.exceptions.PermissionDenied: If access is denied
36
    """
37
```
38

39
### Namespaced Tag Value Retrieval
40

41
Retrieve a TagValue using its namespaced name format for more intuitive access.
42

43
```python { .api }
44
def get_namespaced_tag_value(
45
    self,
46
    request: GetNamespacedTagValueRequest = None,
47
    *,
48
    name: str = None,
49
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
50
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
51
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
52
) -> TagValue:
53
    """
54
    Retrieves a TagValue by its namespaced name.
55

56
    Args:
57
        name (str): The namespaced name of the TagValue.
58
            Format: {parent_id}/{tag_key_short_name}/{tag_value_short_name}
59
            Example: 123456789/environment/production
60
        retry: Retry configuration for the request
61
        timeout: Request timeout in seconds
62
        metadata: Additional metadata to send with the request
63

64
    Returns:
65
        TagValue: The requested TagValue resource
66
    """
67
```
68

69
Usage example:
70

71
```python
72
from google.cloud.resourcemanager import TagValuesClient
73

74
client = TagValuesClient()
75

76
# Get by resource name
77
tag_value = client.get_tag_value(name="tagValues/281484271805522")
78
print(f"TagValue: {tag_value.short_name} - {tag_value.description}")
79

80
# Get by namespaced name (more intuitive)
81
tag_value = client.get_namespaced_tag_value(name="123456789/environment/production")
82
print(f"TagValue: {tag_value.short_name} under {tag_value.parent}")
83
```
84

85
### Tag Value Listing
86

87
List all TagValues under a specified TagKey.
88

89
```python { .api }
90
def list_tag_values(
91
    self,
92
    request: ListTagValuesRequest = None,
93
    *,
94
    parent: str = None,
95
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
96
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
97
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
98
) -> pagers.ListTagValuesPager:
99
    """
100
    Lists TagValues that are direct children of the specified TagKey.
101

102
    Args:
103
        parent (str): The parent TagKey whose TagValues are to be listed.
104
            Format: tagKeys/{tag_key_id}
105
        retry: Retry configuration for the request
106
        timeout: Request timeout in seconds
107
        metadata: Additional metadata to send with the request
108

109
    Returns:
110
        ListTagValuesPager: An iterator over TagValues that automatically
111
                           handles pagination
112
    """
113
```
114

115
Usage example:
116

117
```python
118
client = TagValuesClient()
119

120
# List all TagValues under a TagKey
121
for tag_value in client.list_tag_values(parent="tagKeys/281484271805521"):
122
    print(f"TagValue: {tag_value.short_name} - {tag_value.description}")
123
    print(f"  Namespaced: {tag_value.namespaced_name}")
124
```
125

126
### Tag Value Creation
127

128
Create new TagValues under existing TagKeys. This is a long-running operation.
129

130
```python { .api }
131
def create_tag_value(
132
    self,
133
    request: CreateTagValueRequest = None,
134
    *,
135
    tag_value: TagValue = None,
136
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
137
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
138
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
139
) -> operation.Operation:
140
    """
141
    Creates a new TagValue. This is a long-running operation.
142

143
    Args:
144
        tag_value (TagValue): The TagValue resource to create
145
        retry: Retry configuration for the request
146
        timeout: Request timeout in seconds
147
        metadata: Additional metadata to send with the request
148

149
    Returns:
150
        Operation: Long-running operation that resolves to the created TagValue
151
    """
152
```
153

154
Usage example:
155

156
```python
157
from google.cloud.resourcemanager import TagValuesClient
158
from google.cloud.resourcemanager_v3.types import TagValue
159

160
client = TagValuesClient()
161

162
new_tag_value = TagValue(
163
    parent="tagKeys/281484271805521",  # Must be an existing TagKey
164
    short_name="production",
165
    description="Production environment resources"
166
)
167

168
operation = client.create_tag_value(tag_value=new_tag_value)
169
result = operation.result()  # Wait for completion
170
print(f"Created TagValue: {result.short_name} ({result.name})")
171
print(f"Namespaced name: {result.namespaced_name}")
172
```
173

174
### Tag Value Updates
175

176
Update TagValue attributes such as description. This is a long-running operation.
177

178
```python { .api }
179
def update_tag_value(
180
    self,
181
    request: UpdateTagValueRequest = None,
182
    *,
183
    tag_value: TagValue = None,
184
    update_mask: field_mask_pb2.FieldMask = None,
185
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
186
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
187
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
188
) -> operation.Operation:
189
    """
190
    Updates the specified TagValue. This is a long-running operation.
191

192
    Args:
193
        tag_value (TagValue): The TagValue resource with updated values
194
        update_mask (FieldMask): Fields to update. If not provided,
195
                               all mutable fields are updated
196
        retry: Retry configuration for the request
197
        timeout: Request timeout in seconds
198
        metadata: Additional metadata to send with the request
199

200
    Returns:
201
        Operation: Long-running operation that resolves to the updated TagValue
202
    """
203
```
204

205
Usage example:
206

207
```python
208
from google.protobuf import field_mask_pb2
209

210
client = TagValuesClient()
211

212
# Get existing TagValue
213
tag_value = client.get_tag_value(name="tagValues/281484271805522")
214

215
# Update description
216
tag_value.description = "Updated production environment resources"
217

218
# Specify which fields to update
219
update_mask = field_mask_pb2.FieldMask(paths=["description"])
220

221
operation = client.update_tag_value(
222
    tag_value=tag_value,
223
    update_mask=update_mask
224
)
225
result = operation.result()
226
print(f"Updated TagValue: {result.description}")
227
```
228

229
### Tag Value Deletion
230

231
Delete TagValues if no TagBindings exist. This is a long-running operation that permanently removes the TagValue.
232

233
```python { .api }
234
def delete_tag_value(
235
    self,
236
    request: DeleteTagValueRequest = None,
237
    *,
238
    name: str = None,
239
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
240
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
241
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
242
) -> operation.Operation:
243
    """
244
    Deletes a TagValue if no TagBindings exist. This is a long-running operation.
245
    
246
    The TagValue must have no active TagBindings to be deleted.
247

248
    Args:
249
        name (str): The resource name of the TagValue to delete.
250
                   Format: tagValues/{tag_value_id}
251
        retry: Retry configuration for the request
252
        timeout: Request timeout in seconds
253
        metadata: Additional metadata to send with the request
254

255
    Returns:
256
        Operation: Long-running operation with no return value
257

258
    Raises:
259
        google.api_core.exceptions.FailedPrecondition: If TagValue has active TagBindings
260
    """
261
```
262

263
Usage example:
264

265
```python
266
client = TagValuesClient()
267

268
# Delete a TagValue (only works if no TagBindings exist)
269
operation = client.delete_tag_value(name="tagValues/281484271805522")
270
operation.result()  # Wait for completion
271
print("TagValue deleted successfully")
272
```
273

274
### IAM Policy Management
275

276
Manage IAM (Identity and Access Management) policies for TagValues, controlling who can bind these tags to resources.
277

278
```python { .api }
279
def get_iam_policy(
280
    self,
281
    request: iam_policy_pb2.GetIamPolicyRequest = None,
282
    *,
283
    resource: str = None,
284
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
285
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
286
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
287
) -> policy_pb2.Policy:
288
    """
289
    Gets the IAM access control policy for a TagValue.
290

291
    Args:
292
        resource (str): Resource name of the TagValue.
293
                       Format: tagValues/{tag_value_id}
294

295
    Returns:
296
        Policy: The IAM policy for the TagValue
297
    """
298

299
def set_iam_policy(
300
    self,
301
    request: iam_policy_pb2.SetIamPolicyRequest = None,
302
    *,
303
    resource: str = None,
304
    policy: policy_pb2.Policy = None,
305
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
306
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
307
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
308
) -> policy_pb2.Policy:
309
    """
310
    Sets the IAM access control policy for a TagValue.
311

312
    Args:
313
        resource (str): Resource name of the TagValue
314
        policy (Policy): The new IAM policy
315

316
    Returns:
317
        Policy: The updated IAM policy
318
    """
319

320
def test_iam_permissions(
321
    self,
322
    request: iam_policy_pb2.TestIamPermissionsRequest = None,
323
    *,
324
    resource: str = None,
325
    permissions: MutableSequence[str] = None,
326
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
327
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
328
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
329
) -> iam_policy_pb2.TestIamPermissionsResponse:
330
    """
331
    Tests the specified permissions against the IAM policy for a TagValue.
332

333
    Args:
334
        resource (str): Resource name of the TagValue
335
        permissions (Sequence[str]): List of permissions to test
336

337
    Returns:
338
        TestIamPermissionsResponse: Results of the permission test
339
    """
340
```
341

342
## Types
343

344
```python { .api }
345
class TagValue:
346
    name: str  # Resource name: tagValues/{tag_value_id}
347
    parent: str  # Parent TagKey: tagKeys/{tag_key_id}
348
    short_name: str  # User-assigned short name (e.g., "production")
349
    namespaced_name: str  # Computed field: {parent_org_id}/{tag_key_short_name}/{short_name}
350
    display_name: str  # Human-readable display name
351
    description: str  # Description of the TagValue's purpose
352
    create_time: timestamp_pb2.Timestamp  # Creation timestamp
353
    update_time: timestamp_pb2.Timestamp  # Last update timestamp
354
    etag: str  # Entity tag for optimistic concurrency
355

356
# Request/Response types
357
class GetTagValueRequest:
358
    name: str
359

360
class GetNamespacedTagValueRequest:
361
    name: str  # Format: {parent_org_id}/{tag_key_short_name}/{tag_value_short_name}
362

363
class ListTagValuesRequest:
364
    parent: str  # Format: tagKeys/{tag_key_id}
365
    page_token: str
366
    page_size: int
367

368
class ListTagValuesResponse:
369
    tag_values: MutableSequence[TagValue]
370
    next_page_token: str
371

372
class CreateTagValueRequest:
373
    tag_value: TagValue
374
    validate_only: bool  # If true, validate request without creating
375

376
class UpdateTagValueRequest:
377
    tag_value: TagValue
378
    update_mask: field_mask_pb2.FieldMask
379
    validate_only: bool
380

381
class DeleteTagValueRequest:
382
    name: str
383
    validate_only: bool
384
    etag: str  # Current etag for optimistic concurrency
385

386
# Metadata types for long-running operations
387
class CreateTagValueMetadata:
388
    # Empty metadata message
389

390
class UpdateTagValueMetadata:
391
    # Empty metadata message
392

393
class DeleteTagValueMetadata:
394
    # Empty metadata message
395
```
396

397
## Notes
398

399
TagValues must be created under existing TagKeys and follow a hierarchical naming structure. The namespaced name provides a human-readable path that makes it easier to understand the tag hierarchy, following the format: `{organization_id}/{tag_key_short_name}/{tag_value_short_name}`.
400

401
TagValues cannot be deleted if they have active TagBindings. You must first remove all TagBindings for a TagValue before it can be deleted.