0
# Tag Keys Management
1

2
Management of tag categories that define the taxonomy for organizing and controlling Google Cloud resources through policy and automation. TagKeys represent the "key" portion of key-value tags and define what types of tags can be applied to resources.
3

4
## Capabilities
5

6
### Tag Key Retrieval
7

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

10
```python { .api }
11
def get_tag_key(
12
    self,
13
    request: GetTagKeyRequest = 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
) -> TagKey:
20
    """
21
    Retrieves a TagKey identified by the specified resource name.
22

23
    Args:
24
        name (str): The resource name of the TagKey to retrieve.
25
            Format: tagKeys/{tag_key_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
        TagKey: The requested TagKey resource
32

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

39
### Namespaced Tag Key Retrieval
40

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

43
```python { .api }
44
def get_namespaced_tag_key(
45
    self,
46
    request: GetNamespacedTagKeyRequest = 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
) -> TagKey:
53
    """
54
    Retrieves a TagKey by its namespaced name.
55

56
    Args:
57
        name (str): The namespaced name of the TagKey.
58
            Format: {parent_id}/{tag_key_short_name}
59
            Example: 123456789/environment
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
        TagKey: The requested TagKey resource
66
    """
67
```
68

69
Usage example:
70

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

74
client = TagKeysClient()
75

76
# Get by resource name
77
tag_key = client.get_tag_key(name="tagKeys/281484271805521")
78
print(f"TagKey: {tag_key.short_name} - {tag_key.description}")
79

80
# Get by namespaced name (more intuitive)
81
tag_key = client.get_namespaced_tag_key(name="123456789/environment")
82
print(f"TagKey: {tag_key.short_name} (Purpose: {tag_key.purpose})")
83
```
84

85
### Tag Key Listing
86

87
List all TagKeys under a specified parent resource (organization or project).
88

89
```python { .api }
90
def list_tag_keys(
91
    self,
92
    request: ListTagKeysRequest = 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.ListTagKeysPager:
99
    """
100
    Lists TagKeys that are direct children of the specified parent resource.
101

102
    Args:
103
        parent (str): The parent resource whose TagKeys are to be listed.
104
            Formats: organizations/{organization_id} or projects/{project_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
        ListTagKeysPager: An iterator over TagKeys that automatically
111
                         handles pagination
112
    """
113
```
114

115
Usage example:
116

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

120
# List all TagKeys under an organization
121
for tag_key in client.list_tag_keys(parent="organizations/123456789"):
122
    print(f"TagKey: {tag_key.short_name} - {tag_key.description}")
123
    print(f"  Purpose: {tag_key.purpose}")
124
    print(f"  Namespaced: {tag_key.namespaced_name}")
125
```
126

127
### Tag Key Creation
128

129
Create new TagKeys to define tag categories. This is a long-running operation with a limit of 1000 TagKeys per parent resource.
130

131
```python { .api }
132
def create_tag_key(
133
    self,
134
    request: CreateTagKeyRequest = None,
135
    *,
136
    tag_key: TagKey = None,
137
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
138
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
139
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
140
) -> operation.Operation:
141
    """
142
    Creates a new TagKey. This is a long-running operation.
143
    
144
    Maximum of 1000 TagKeys per parent resource.
145

146
    Args:
147
        tag_key (TagKey): The TagKey resource to create
148
        retry: Retry configuration for the request
149
        timeout: Request timeout in seconds
150
        metadata: Additional metadata to send with the request
151

152
    Returns:
153
        Operation: Long-running operation that resolves to the created TagKey
154
    """
155
```
156

157
Usage example:
158

159
```python
160
from google.cloud.resourcemanager import TagKeysClient
161
from google.cloud.resourcemanager_v3.types import TagKey, Purpose
162

163
client = TagKeysClient()
164

165
new_tag_key = TagKey(
166
    parent="organizations/123456789",
167
    short_name="environment",
168
    description="Environment classification for resources",
169
    purpose=Purpose.GCE_FIREWALL  # Optional: specific purpose for the tag
170
)
171

172
operation = client.create_tag_key(tag_key=new_tag_key)
173
result = operation.result()  # Wait for completion
174
print(f"Created TagKey: {result.short_name} ({result.name})")
175
print(f"Namespaced name: {result.namespaced_name}")
176
```
177

178
### Tag Key Updates
179

180
Update TagKey attributes such as description and purpose data. This is a long-running operation.
181

182
```python { .api }
183
def update_tag_key(
184
    self,
185
    request: UpdateTagKeyRequest = None,
186
    *,
187
    tag_key: TagKey = None,
188
    update_mask: field_mask_pb2.FieldMask = None,
189
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
190
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
191
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
192
) -> operation.Operation:
193
    """
194
    Updates the specified TagKey. This is a long-running operation.
195

196
    Args:
197
        tag_key (TagKey): The TagKey resource with updated values
198
        update_mask (FieldMask): Fields to update. If not provided,
199
                               all mutable fields are updated
200
        retry: Retry configuration for the request
201
        timeout: Request timeout in seconds
202
        metadata: Additional metadata to send with the request
203

204
    Returns:
205
        Operation: Long-running operation that resolves to the updated TagKey
206
    """
207
```
208

209
Usage example:
210

211
```python
212
from google.protobuf import field_mask_pb2
213

214
client = TagKeysClient()
215

216
# Get existing TagKey
217
tag_key = client.get_tag_key(name="tagKeys/281484271805521")
218

219
# Update description
220
tag_key.description = "Updated environment classification for all resources"
221

222
# Specify which fields to update
223
update_mask = field_mask_pb2.FieldMask(paths=["description"])
224

225
operation = client.update_tag_key(
226
    tag_key=tag_key,
227
    update_mask=update_mask
228
)
229
result = operation.result()
230
print(f"Updated TagKey: {result.description}")
231
```
232

233
### Tag Key Deletion
234

235
Delete TagKeys if no child TagValues exist. This is a long-running operation that permanently removes the TagKey.
236

237
```python { .api }
238
def delete_tag_key(
239
    self,
240
    request: DeleteTagKeyRequest = None,
241
    *,
242
    name: str = None,
243
    retry: OptionalRetry = gapic_v1.method.DEFAULT,
244
    timeout: Union[float, object] = gapic_v1.method.DEFAULT,
245
    metadata: Sequence[Tuple[str, Union[str, bytes]]] = ()
246
) -> operation.Operation:
247
    """
248
    Deletes a TagKey if no child TagValues exist. This is a long-running operation.
249
    
250
    The TagKey must have no child TagValues to be deleted.
251

252
    Args:
253
        name (str): The resource name of the TagKey to delete.
254
                   Format: tagKeys/{tag_key_id}
255
        retry: Retry configuration for the request
256
        timeout: Request timeout in seconds
257
        metadata: Additional metadata to send with the request
258

259
    Returns:
260
        Operation: Long-running operation with no return value
261

262
    Raises:
263
        google.api_core.exceptions.FailedPrecondition: If TagKey has child TagValues
264
    """
265
```
266

267
Usage example:
268

269
```python
270
client = TagKeysClient()
271

272
# Delete a TagKey (only works if no child TagValues exist)
273
operation = client.delete_tag_key(name="tagKeys/281484271805521")
274
operation.result()  # Wait for completion
275
print("TagKey deleted successfully")
276
```
277

278
### IAM Policy Management
279

280
Manage IAM (Identity and Access Management) policies for TagKeys, controlling who can create TagValues and bind tags.
281

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

295
    Args:
296
        resource (str): Resource name of the TagKey.
297
                       Format: tagKeys/{tag_key_id}
298

299
    Returns:
300
        Policy: The IAM policy for the TagKey
301
    """
302

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

316
    Args:
317
        resource (str): Resource name of the TagKey
318
        policy (Policy): The new IAM policy
319

320
    Returns:
321
        Policy: The updated IAM policy
322
    """
323

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

337
    Args:
338
        resource (str): Resource name of the TagKey
339
        permissions (Sequence[str]): List of permissions to test
340

341
    Returns:
342
        TestIamPermissionsResponse: Results of the permission test
343
    """
344
```
345

346
## Types
347

348
```python { .api }
349
class TagKey:
350
    name: str  # Resource name: tagKeys/{tag_key_id}
351
    parent: str  # Parent resource: organizations/{org_id} or projects/{project_id}
352
    short_name: str  # User-assigned short name (e.g., "environment")
353
    namespaced_name: str  # Computed field: {parent_id}/{short_name}
354
    display_name: str  # Human-readable display name
355
    description: str  # Description of the TagKey's purpose
356
    purpose: Purpose  # Specific purpose for the TagKey
357
    purpose_data: MutableMapping[str, str]  # Additional purpose-specific data
358
    create_time: timestamp_pb2.Timestamp  # Creation timestamp
359
    update_time: timestamp_pb2.Timestamp  # Last update timestamp
360
    etag: str  # Entity tag for optimistic concurrency
361

362
class Purpose(proto.Enum):
363
    """Enum defining specific purposes for TagKeys."""
364
    PURPOSE_UNSPECIFIED = 0
365
    GCE_FIREWALL = 1  # Used for GCE firewall rules
366

367
# Request/Response types
368
class GetTagKeyRequest:
369
    name: str
370

371
class GetNamespacedTagKeyRequest:
372
    name: str  # Format: {parent_id}/{tag_key_short_name}
373

374
class ListTagKeysRequest:
375
    parent: str
376
    page_token: str
377
    page_size: int
378

379
class ListTagKeysResponse:
380
    tag_keys: MutableSequence[TagKey]
381
    next_page_token: str
382

383
class CreateTagKeyRequest:
384
    tag_key: TagKey
385
    validate_only: bool  # If true, validate request without creating
386

387
class UpdateTagKeyRequest:
388
    tag_key: TagKey
389
    update_mask: field_mask_pb2.FieldMask
390
    validate_only: bool
391

392
class DeleteTagKeyRequest:
393
    name: str
394
    validate_only: bool
395
    etag: str  # Current etag for optimistic concurrency
396

397
# Metadata types for long-running operations
398
class CreateTagKeyMetadata:
399
    # Empty metadata message
400

401
class UpdateTagKeyMetadata:
402
    # Empty metadata message
403

404
class DeleteTagKeyMetadata:
405
    # Empty metadata message
406
```