Skip to main content

tags

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

Overview​

Nametags
TypeResource
Idoci.identity.tags

Fields​

The following fields are returned by SELECT queries:

The tag was retrieved.

NameDatatypeDescription
idstringThe OCID of the tag definition.
namestringThe name assigned to the tag during creation. This is the tag key definition. The name must be unique within the tag namespace and cannot be changed.
compartmentIdstringThe OCID of the compartment that contains the tag definition.
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.
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"}
isCostTrackingbooleanIndicates whether the tag is enabled for cost tracking.
isRetiredbooleanIndicates whether the tag is retired. See [Retiring Key Definitions and Namespace Definitions](/Content/Tagging/Tasks/managingtagsandtagnamespaces.htm#retiringkeys).
lifecycleStatestringThe tag's current state. After creating a tag, make sure its lifecycleState is ACTIVE before using it. After retiring a tag, make sure its lifecycleState is INACTIVE before using it. If you delete a tag, you cannot delete another tag until the deleted tag's lifecycleState changes from DELETING to DELETED. (ACTIVE, INACTIVE, DELETING, DELETED)
systemTagsobjectThe system tags for this resource. Each key is predefined and scoped to a namespace. Example: {"orcl-cloud": {"free-tier-retained": "true"}}
tagNamespaceIdstringThe OCID of the namespace that contains the tag definition.
tagNamespaceNamestringThe name of the tag namespace that contains the tag definition.
timeCreatedstring (date-time)Date and time the tag was created, in the format defined by RFC3339. Example: 2016-08-25T21:10:29.600Z
validatorobjectValidates a definedTag value. Each validator performs validation steps in addition to the standard validation for definedTag values. For more information, see [Limits on Tags](/Content/Tagging/Concepts/taggingoverview.htm#limits). If you define a validator after a value has been set for a defined tag, then any updates that attempt to change the value must pass the additional validation defined by the current rule. Previously set values (even those that would fail the current validation) are not updated. You can still update other attributes to resources that contain a non-valid defined tag. To clear the validator call UpdateTag with [DefaultTagDefinitionValidator](/api/#/en/identity/latest/datatypes/DefaultTagDefinitionValidator).

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselecttagNamespaceId, tagName, regionGets the specified tag's information.
listselecttagNamespaceId, regionpage, limit, lifecycleStateLists the tag definitions in the specified tag namespace.<br />
createinserttagNamespaceId, region, name, descriptionopc-retry-token, isLockOverrideCreates a new tag in the specified tag namespace.<br /><br />The tag requires either the OCID or the name of the tag namespace that will contain this<br />tag definition.<br /><br />You must specify a name for the tag, which must be unique across all tags in the tag namespace<br />and cannot be changed. The name can contain any ASCII character except the space (_) or period (.) characters.<br />Names are case insensitive. That means, for example, "myTag" and "mytag" are not allowed in the same namespace.<br />If you specify a name that's already in use in the tag namespace, a 409 error is returned.<br /><br />The tag must have a description. It does not have to be unique, and you can change it with<br />[UpdateTag](#/en/identity/latest/Tag/UpdateTag).<br /><br />The tag must have a value type, which is specified with a validator. Tags can use either a<br />static value or a list of possible values. Static values are entered by a user applying the tag<br />to a resource. Lists are created by you and the user must apply a value from the list. Lists<br />are validiated.<br /><br />* If no validator is set, the user applying the tag to a resource can type in a static<br />value or leave the tag value empty.<br />* If a validator is set, the user applying the tag to a resource must select from a list<br />of values that you supply with [EnumTagDefinitionValidator](#/en/identity/latest/datatypes/EnumTagDefinitionValidator).<br />
updateupdatetagNamespaceId, tagName, regionif-match, isLockOverrideUpdates the specified tag definition.<br /><br />Setting validator determines the value type. Tags can use either a static value or a<br />list of possible values. Static values are entered by a user applying the tag to a resource.<br />Lists are created by you and the user must apply a value from the list. On update, any values<br />in a list that were previously set do not change, but new values must pass validation. Values<br />already applied to a resource do not change.<br /><br />You cannot remove list values that appear in a TagDefault. To remove a list value that<br />appears in a TagDefault, first update the TagDefault to use a different value.<br />
deletedeletetagNamespaceId, tagName, regionif-match, isLockOverrideDeletes the specified tag definition. This operation triggers a process that removes the<br />tag from all resources in your tenancy.<br /><br />These things happen immediately:<br /> * If the tag was a cost-tracking tag, it no longer counts against your 10 cost-tracking<br /> tags limit, whether you first disabled it or not.<br /> * If the tag was used with dynamic groups, none of the rules that contain the tag will<br /> be evaluated against the tag.<br /><br />When you start the delete operation, the state of the tag changes to DELETING and tag removal<br />from resources begins. This can take up to 48 hours depending on the number of resources that<br />were tagged as well as the regions in which those resources reside.<br /><br />When all tags have been removed, the state changes to DELETED. You cannot restore a deleted tag. Once the deleted tag<br />changes its state to DELETED, you can use the same tag name again.<br /><br />After you start this operation, you cannot start either the [BulkDeleteTags](#/en/identity/20160918/Tag/BulkDeleteTags) or the [CascadeDeleteTagNamespace](#/en/identity/20160918/TagNamespace/CascadeDeleteTagNamespace) operation until this process completes.<br /><br />To delete a tag, you must first retire it. Use [UpdateTag](#/en/identity/latest/Tag/UpdateTag)<br />to retire a tag.<br />
bulk_delete_tagsexecregion, tagDefinitionIdsopc-request-id, opc-retry-token, isLockOverrideDeletes the specified tag key definitions. This operation triggers a process that removes the<br />tags from all resources in your tenancy. The tag key definitions must be within the same tag namespace.<br /><br />The following actions happen immediately:<br /><br /> * If the tag is a cost-tracking tag, the tag no longer counts against your<br /> 10 cost-tracking tags limit, even if you do not disable the tag before running this operation.<br /> * If the tag is used with dynamic groups, the rules that contain the tag are no longer<br /> evaluated against the tag.<br /><br />After you start this operation, the state of the tag changes to DELETING, and tag removal<br />from resources begins. This process can take up to 48 hours depending on the number of resources that<br />are tagged and the regions in which those resources reside.<br /><br />When all tags have been removed, the state changes to DELETED. You cannot restore a deleted tag. After the tag state<br />changes to DELETED, you can use the same tag name again.<br /><br />After you start this operation, you cannot start either the [DeleteTag](#/en/identity/20160918/Tag/DeleteTag) or the [CascadeDeleteTagNamespace](#/en/identity/20160918/TagNamespace/CascadeDeleteTagNamespace) operation until this process completes.<br /><br />In order to delete tags, you must first retire the tags. Use [UpdateTag](#/en/identity/20160918/Tag/UpdateTag)<br />to retire a tag.<br />
bulk_edit_tagsexecregion, compartmentId, resources, bulkEditOperationsopc-request-id, opc-retry-tokenEdits the specified list of tag key definitions for the selected resources.<br />This operation triggers a process that edits the tags on all selected resources. The possible actions are:<br /><br /> * Add a defined tag when the tag does not already exist on the resource.<br /> * Update the value for a defined tag when the tag is present on the resource.<br /> * Add a defined tag when it does not already exist on the resource or update the value for a defined tag when the tag is present on the resource.<br /> * Remove a defined tag from a resource. The tag is removed from the resource regardless of the tag value.<br /><br />See [BulkEditOperationDetails](#/en/identity/latest/datatypes/BulkEditOperationDetails) for more information.<br /><br />The edits can include a combination of operations and tag sets.<br />However, multiple operations cannot apply to one key definition in the same request.<br />For example, if one request adds tag set-1 to a resource and sets a tag value to tag set-2,<br />tag set-1 and tag set-2 cannot have any common tag definitions.<br />
import_standard_tagsexecregion, compartmentId, standardTagNamespaceNameopc-request-id, opc-retry-tokenOCI will release Tag Namespaces that our customers can import.<br />These Tag Namespaces will provide Tags for our customers and Partners to provide consistency and enable data reporting.<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
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)
tagNamestringThe name of the tag.
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.
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's information.

SELECT
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
isCostTracking,
isRetired,
lifecycleState,
systemTags,
tagNamespaceId,
tagNamespaceName,
timeCreated,
validator
FROM oci.identity.tags
WHERE tagNamespaceId = '{{ tagNamespaceId }}' -- required
AND tagName = '{{ tagName }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples​

Creates a new tag in the specified tag namespace.<br /><br />The tag requires either the OCID or the name of the tag namespace that will contain this<br />tag definition.<br /><br />You must specify a name for the tag, which must be unique across all tags in the tag namespace<br />and cannot be changed. The name can contain any ASCII character except the space (_) or period (.) characters.<br />Names are case insensitive. That means, for example, "myTag" and "mytag" are not allowed in the same namespace.<br />If you specify a name that's already in use in the tag namespace, a 409 error is returned.<br /><br />The tag must have a description. It does not have to be unique, and you can change it with<br />[UpdateTag](#/en/identity/latest/Tag/UpdateTag).<br /><br />The tag must have a value type, which is specified with a validator. Tags can use either a<br />static value or a list of possible values. Static values are entered by a user applying the tag<br />to a resource. Lists are created by you and the user must apply a value from the list. Lists<br />are validiated.<br /><br />* If no validator is set, the user applying the tag to a resource can type in a static<br />value or leave the tag value empty.<br />* If a validator is set, the user applying the tag to a resource must select from a list<br />of values that you supply with [EnumTagDefinitionValidator](#/en/identity/latest/datatypes/EnumTagDefinitionValidator).<br />

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

UPDATE examples​

Updates the specified tag definition.<br /><br />Setting validator determines the value type. Tags can use either a static value or a<br />list of possible values. Static values are entered by a user applying the tag to a resource.<br />Lists are created by you and the user must apply a value from the list. On update, any values<br />in a list that were previously set do not change, but new values must pass validation. Values<br />already applied to a resource do not change.<br /><br />You cannot remove list values that appear in a TagDefault. To remove a list value that<br />appears in a TagDefault, first update the TagDefault to use a different value.<br />

UPDATE oci.identity.tags
SET 
definedTags = '{{ definedTags }}',
description = '{{ description }}',
freeformTags = '{{ freeformTags }}',
isCostTracking = {{ isCostTracking }},
isRetired = {{ isRetired }},
validator = '{{ validator }}'
WHERE 
tagNamespaceId = '{{ tagNamespaceId }}' --required
AND tagName = '{{ tagName }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
AND isLockOverride = {{ isLockOverride}}
RETURNING
id,
name,
compartmentId,
definedTags,
description,
freeformTags,
isCostTracking,
isRetired,
lifecycleState,
systemTags,
tagNamespaceId,
tagNamespaceName,
timeCreated,
validator;

DELETE examples​

Deletes the specified tag definition. This operation triggers a process that removes the<br />tag from all resources in your tenancy.<br /><br />These things happen immediately:<br /> * If the tag was a cost-tracking tag, it no longer counts against your 10 cost-tracking<br /> tags limit, whether you first disabled it or not.<br /> * If the tag was used with dynamic groups, none of the rules that contain the tag will<br /> be evaluated against the tag.<br /><br />When you start the delete operation, the state of the tag changes to DELETING and tag removal<br />from resources begins. This can take up to 48 hours depending on the number of resources that<br />were tagged as well as the regions in which those resources reside.<br /><br />When all tags have been removed, the state changes to DELETED. You cannot restore a deleted tag. Once the deleted tag<br />changes its state to DELETED, you can use the same tag name again.<br /><br />After you start this operation, you cannot start either the [BulkDeleteTags](#/en/identity/20160918/Tag/BulkDeleteTags) or the [CascadeDeleteTagNamespace](#/en/identity/20160918/TagNamespace/CascadeDeleteTagNamespace) operation until this process completes.<br /><br />To delete a tag, you must first retire it. Use [UpdateTag](#/en/identity/latest/Tag/UpdateTag)<br />to retire a tag.<br />

DELETE FROM oci.identity.tags
WHERE tagNamespaceId = '{{ tagNamespaceId }}' --required
AND tagName = '{{ tagName }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
AND isLockOverride = '{{ isLockOverride }}'
;

Lifecycle Methods​

Deletes the specified tag key definitions. This operation triggers a process that removes the<br />tags from all resources in your tenancy. The tag key definitions must be within the same tag namespace.<br /><br />The following actions happen immediately:<br /><br /> * If the tag is a cost-tracking tag, the tag no longer counts against your<br /> 10 cost-tracking tags limit, even if you do not disable the tag before running this operation.<br /> * If the tag is used with dynamic groups, the rules that contain the tag are no longer<br /> evaluated against the tag.<br /><br />After you start this operation, the state of the tag changes to DELETING, and tag removal<br />from resources begins. This process can take up to 48 hours depending on the number of resources that<br />are tagged and the regions in which those resources reside.<br /><br />When all tags have been removed, the state changes to DELETED. You cannot restore a deleted tag. After the tag state<br />changes to DELETED, you can use the same tag name again.<br /><br />After you start this operation, you cannot start either the [DeleteTag](#/en/identity/20160918/Tag/DeleteTag) or the [CascadeDeleteTagNamespace](#/en/identity/20160918/TagNamespace/CascadeDeleteTagNamespace) operation until this process completes.<br /><br />In order to delete tags, you must first retire the tags. Use [UpdateTag](#/en/identity/20160918/Tag/UpdateTag)<br />to retire a tag.<br />

EXEC oci.identity.tags.bulk_delete_tags 
@region='{{ region }}' --required, 
@opc-request-id='{{ opc-request-id }}', 
@opc-retry-token='{{ opc-retry-token }}', 
@isLockOverride={{ isLockOverride }} 
@@json=
'{
"tagDefinitionIds": "{{ tagDefinitionIds }}"
}'
;