Skip to main content

tag_namespaces

Creates, updates, deletes, gets or lists a tag_namespaces resource.

Overview​

Nametag_namespaces
TypeResource
Idoci.identity.tag_namespaces

Fields​

The following fields are returned by SELECT queries:

The tagNamespace was retrieved.

NameDatatypeDescription
idstringThe OCID of the tag namespace.
namestringThe name of the tag namespace. It must be unique across all tag namespaces in the tenancy and cannot be changed.
compartmentIdstringThe OCID of the compartment that contains the tag namespace.
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
descriptionstringThe description you assign to the tag namespace.
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
isRetiredbooleanWhether the tag namespace is retired. See [Retiring Key Definitions and Namespace Definitions](/Content/Tagging/Tasks/managingtagsandtagnamespaces.htm#retiringkeys).
lifecycleStatestringThe tagnamespace's current state. After creating a tagnamespace, make sure its lifecycleState is ACTIVE before using it. After retiring a tagnamespace, make sure its lifecycleState is INACTIVE before using it. (ACTIVE, INACTIVE, DELETING, DELETED)
locksarrayLocks associated with this resource.
systemTagsobjectUsage of system tag keys. These predefined keys are scoped to namespaces. Example: {"orcl-cloud": {"free-tier-retained": "true"}}
timeCreatedstring (date-time)Date and time the tagNamespace was created, in the format defined by RFC3339. Example: 2016-08-25T21:10:29.600Z

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselecttagNamespaceId, regionGets the specified tag namespace's information.<br />
listselectcompartmentId, regionpage, limit, includeSubcompartments, lifecycleStateLists the tag namespaces in the specified compartment.<br />
createinsertregion, name, compartmentId, descriptionopc-retry-tokenCreates a new tag namespace in the specified compartment.<br /><br />You must specify the compartment ID in the request object (remember that the tenancy is simply the root<br />compartment).<br /><br />You must also specify a name for the namespace, which must be unique across all namespaces in your tenancy<br />and cannot be changed. The name can contain any ASCII character except the space (_) or period (.).<br />Names are case insensitive. That means, for example, "myNamespace" and "mynamespace" are not allowed<br />in the same tenancy. Once you created a namespace, you cannot change the name.<br />If you specify a name that's already in use in the tenancy, a 409 error is returned.<br /><br />You must also specify a description for the namespace.<br />It does not have to be unique, and you can change it with<br />[UpdateTagNamespace](#/en/identity/latest/TagNamespace/UpdateTagNamespace).<br />
updateupdatetagNamespaceId, regionisLockOverrideUpdates the the specified tag namespace. You can't update the namespace name.<br /><br />Updating isRetired to 'true' retires the namespace and all the tag definitions in the namespace. Reactivating a<br />namespace (changing isRetired from 'true' to 'false') does not reactivate tag definitions.<br />To reactivate the tag definitions, you must reactivate each one individually after you reactivate the namespace,<br />using [UpdateTag](#/en/identity/20160918/Tag/UpdateTag). For more information about retiring tag namespaces, see<br />[Retiring Key Definitions and Namespace Definitions](/Content/Tagging/Tasks/managingtagsandtagnamespaces.htm#retiringkeys).<br /><br />You can't add a namespace with the same name as a retired namespace in the same tenancy.<br />
deletedeletetagNamespaceId, regionif-match, opc-request-id, isLockOverrideDeletes the specified tag namespace. Only an empty tag namespace can be deleted with this operation. To use this operation<br />to delete a tag namespace that contains tag definitions, first delete all of its tag definitions.<br /><br />Use [CascadeDeleteTagNamespace](#/en/identity/20160918/TagNamespace/CascadeDeleteTagNamespace) to delete a tag namespace along with all of<br />the tag definitions contained within that namespace.<br /><br />Use [DeleteTag](#/en/identity/latest/Tag/DeleteTag) to delete a tag definition.<br />
add_tag_namespace_lockexectagNamespaceId, region, typeif-match, opc-request-id, opc-retry-tokenAdd a resource lock to a tag namespace.<br />
cascade_delete_tag_namespaceexectagNamespaceId, regionif-match, opc-request-id, opc-retry-token, isLockOverrideDeletes the specified tag namespace. This operation triggers a process that removes all of the tags<br />defined in the specified tag namespace from all resources in your tenancy and then deletes the tag namespace.<br /><br />After you start the delete operation:<br /><br /> * New tag key definitions cannot be created under the namespace.<br /> * The state of the tag namespace changes to DELETING.<br /> * Tag removal from the resources begins.<br /><br />This process can take up to 48 hours depending on the number of tag definitions in the namespace, the number of resources<br />that are tagged, and the locations of the regions in which those resources reside.<br /><br />After all tags are removed, the state changes to DELETED. You cannot restore a deleted tag namespace. After the deleted tag namespace<br />changes its state to DELETED, you can use the name of the deleted tag namespace again.<br /><br />After you start this operation, you cannot start either the [DeleteTag](#/en/identity/20160918/Tag/DeleteTag) or the [BulkDeleteTags](#/en/identity/20160918/Tag/BulkDeleteTags) operation until this process completes.<br /><br />To delete a tag namespace, you must first retire it. Use [UpdateTagNamespace](#/en/identity/20160918/TagNamespace/UpdateTagNamespace)<br />to retire a tag namespace.<br />
change_compartmentexectagNamespaceId, region, compartmentIdopc-retry-token, isLockOverrideMoves the specified tag namespace to the specified compartment within the same tenancy.<br /><br />To move the tag namespace, you must have the manage tag-namespaces permission on both compartments.<br />For more information about IAM policies, see [Details for IAM](/Content/Identity/policyreference/iampolicyreference.htm).<br /><br />Moving a tag namespace moves all the tag key definitions contained in the tag namespace.<br />
remove_tag_namespace_lockexectagNamespaceId, region, typeif-match, opc-request-id, opc-retry-tokenRemove a resource lock from a tag namespace.<br />

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
compartmentIdstringThe OCID of the compartment (remember that the tenancy is simply the root compartment).
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
tagNamespaceIdstringThe OCID of the tag namespace.
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
includeSubcompartmentsbooleanAn optional boolean parameter indicating whether to retrieve all tag namespaces in subcompartments. If this parameter is not specified, only the tag namespaces defined in the specified compartment are retrieved.
isLockOverridebooleanWhether to override locks (if any exist).
lifecycleStatestringA filter to only return resources that match the given lifecycle state. The state value is case-insensitive.
limitintegerThe maximum number of items to return in a paginated "List" call.
opc-request-idstringUnique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-tokenstringA token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (e.g., if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).
pagestringThe value of the opc-next-page response header from the previous "List" call.

SELECT examples​

Gets the specified tag namespace's information.<br />

SELECT
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
isRetired,
lifecycleState,
locks,
systemTags,
timeCreated
FROM oci.identity.tag_namespaces
WHERE tagNamespaceId = '{{ tagNamespaceId }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new tag namespace in the specified compartment.<br /><br />You must specify the compartment ID in the request object (remember that the tenancy is simply the root<br />compartment).<br /><br />You must also specify a name for the namespace, which must be unique across all namespaces in your tenancy<br />and cannot be changed. The name can contain any ASCII character except the space (_) or period (.).<br />Names are case insensitive. That means, for example, "myNamespace" and "mynamespace" are not allowed<br />in the same tenancy. Once you created a namespace, you cannot change the name.<br />If you specify a name that's already in use in the tenancy, a 409 error is returned.<br /><br />You must also specify a description for the namespace.<br />It does not have to be unique, and you can change it with<br />[UpdateTagNamespace](#/en/identity/latest/TagNamespace/UpdateTagNamespace).<br />

INSERT INTO oci.identity.tag_namespaces (
compartmentId,
definedTags,
description,
freeformTags,
locks,
name,
region,
opc-retry-token
)
SELECT 
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ description }}' /* required */,
'{{ freeformTags }}',
'{{ locks }}',
'{{ name }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}'
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
isRetired,
lifecycleState,
locks,
systemTags,
timeCreated
;

UPDATE examples​

Updates the the specified tag namespace. You can't update the namespace name.<br /><br />Updating isRetired to 'true' retires the namespace and all the tag definitions in the namespace. Reactivating a<br />namespace (changing isRetired from 'true' to 'false') does not reactivate tag definitions.<br />To reactivate the tag definitions, you must reactivate each one individually after you reactivate the namespace,<br />using [UpdateTag](#/en/identity/20160918/Tag/UpdateTag). For more information about retiring tag namespaces, see<br />[Retiring Key Definitions and Namespace Definitions](/Content/Tagging/Tasks/managingtagsandtagnamespaces.htm#retiringkeys).<br /><br />You can't add a namespace with the same name as a retired namespace in the same tenancy.<br />

UPDATE oci.identity.tag_namespaces
SET 
definedTags = '{{ definedTags }}',
description = '{{ description }}',
freeformTags = '{{ freeformTags }}',
isRetired = {{ isRetired }}
WHERE 
tagNamespaceId = '{{ tagNamespaceId }}' --required
AND region = '{{ region }}' --required
AND isLockOverride = {{ isLockOverride}}
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
isRetired,
lifecycleState,
locks,
systemTags,
timeCreated;

DELETE examples​

Deletes the specified tag namespace. Only an empty tag namespace can be deleted with this operation. To use this operation<br />to delete a tag namespace that contains tag definitions, first delete all of its tag definitions.<br /><br />Use [CascadeDeleteTagNamespace](#/en/identity/20160918/TagNamespace/CascadeDeleteTagNamespace) to delete a tag namespace along with all of<br />the tag definitions contained within that namespace.<br /><br />Use [DeleteTag](#/en/identity/latest/Tag/DeleteTag) to delete a tag definition.<br />

DELETE FROM oci.identity.tag_namespaces
WHERE tagNamespaceId = '{{ tagNamespaceId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
AND opc-request-id = '{{ opc-request-id }}'
AND isLockOverride = '{{ isLockOverride }}'
;

Lifecycle Methods​

Add a resource lock to a tag namespace.<br />

EXEC oci.identity.tag_namespaces.add_tag_namespace_lock 
@tagNamespaceId='{{ tagNamespaceId }}' --required, 
@region='{{ region }}' --required, 
@if-match='{{ if-match }}', 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}' 
@@json=
'{
"message": "{{ message }}", 
"relatedResourceId": "{{ relatedResourceId }}", 
"type": "{{ type }}"
}'
;