tags

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

Overview

Name	tags
Type	Resource
Id	digitalocean.compute.tags

Fields

The following fields are returned by SELECT queries:

tags_get

The response will be a JSON object with a key called tag.
The value of this will be a tag object containing the standard tag attributes.

Tagged resources will only include resources that you are authorized to see.

Name	Datatype	Description
name	string	The name of the tag. Tags may contain letters, numbers, colons, dashes, and underscores. There is a limit of 255 characters per tag. Note: Tag names are case stable, which means the capitalization you use when you first create a tag is canonical. When working with tags in the API, you must use the tag's canonical capitalization. For example, if you create a tag named "PROD", the URL to add that tag to a resource would be https://api.digitalocean.com/v2/tags/PROD/resources (not /v2/tags/prod/resources). Tagged resources in the control panel will always display the canonical capitalization. For example, if you create a tag named "PROD", you can tag resources in the control panel by entering "prod". The tag will still display with its canonical capitalization, "PROD". (pattern: ^[a-zA-Z0-9_-:]+$, example: extra-awesome)
resources	object	An embedded object containing key value pairs of resource type and resource statistics. It also includes a count of the total number of resources tagged with the current tag as well as a last_tagged_uri attribute set to the last resource tagged with the current tag. This will only include resources that you are authorized to see. For example, to see tagged Droplets, include the droplet:read scope.

tags_list

To list all of your tags, you can send a GET request to /v2/tags.

Name	Datatype	Description
name	string	The name of the tag. Tags may contain letters, numbers, colons, dashes, and underscores. There is a limit of 255 characters per tag. Note: Tag names are case stable, which means the capitalization you use when you first create a tag is canonical. When working with tags in the API, you must use the tag's canonical capitalization. For example, if you create a tag named "PROD", the URL to add that tag to a resource would be https://api.digitalocean.com/v2/tags/PROD/resources (not /v2/tags/prod/resources). Tagged resources in the control panel will always display the canonical capitalization. For example, if you create a tag named "PROD", you can tag resources in the control panel by entering "prod". The tag will still display with its canonical capitalization, "PROD". (pattern: ^[a-zA-Z0-9_-:]+$, example: extra-awesome)
resources	object	An embedded object containing key value pairs of resource type and resource statistics. It also includes a count of the total number of resources tagged with the current tag as well as a last_tagged_uri attribute set to the last resource tagged with the current tag. This will only include resources that you are authorized to see. For example, to see tagged Droplets, include the droplet:read scope.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
tags_get	select	tag_id		To retrieve an individual tag, you can send a GET request to /v2/tags/$TAG_NAME. This endpoint will only return tagged resources that you are authorized to see. For example, to see tagged Droplets, include the droplet:read scope.
tags_list	select		per_page, page	To list all of your tags, you can send a GET request to /v2/tags. This endpoint will only return tagged resources that you are authorized to see (e.g. Droplets will only be returned if you have droplet:read).
tags_create	insert			To create a tag you can send a POST request to /v2/tags with a name attribute.
tags_delete	delete	tag_id		A tag can be deleted by sending a DELETE request to /v2/tags/$TAG_NAME. Deleting a tag also untags all the resources that have previously been tagged by the Tag
tags_assign_resources	exec	tag_id, resources		Resources can be tagged by sending a POST request to /v2/tags/$TAG_NAME/resources with an array of json objects containing resource_id and resource_type attributes. Currently only tagging of Droplets, Databases, Images, Volumes, and Volume Snapshots is supported. resource_type is expected to be the string droplet, database, image, volume or volume_snapshot. resource_id is expected to be the ID of the resource as a string. In order to tag a resource, you must have both tag:create and <resource type>:update scopes. For example, to tag a Droplet, you must have tag:create and droplet:update.
tags_unassign_resources	exec	tag_id, resources		Resources can be untagged by sending a DELETE request to /v2/tags/$TAG_NAME/resources with an array of json objects containing resource_id and resource_type attributes. Currently only untagging of Droplets, Databases, Images, Volumes, and Volume Snapshots is supported. resource_type is expected to be the string droplet, database, image, volume or volume_snapshot. resource_id is expected to be the ID of the resource as a string. In order to untag a resource, you must have both tag:delete and <resource type>:update scopes. For example, to untag a Droplet, you must have tag:delete and droplet:update.

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.

Name	Datatype	Description
tag_id	string	The name of the tag. Tags may contain letters, numbers, colons, dashes, and underscores. There is a limit of 255 characters per tag. (example: awesome)
page	integer	Which 'page' of paginated results to return. (example: 1)
per_page	integer	Number of items returned per page (example: 2)

SELECT examples

tags_get

To retrieve an individual tag, you can send a GET request to
/v2/tags/$TAG_NAME.

This endpoint will only return tagged resources that you are authorized to see.
For example, to see tagged Droplets, include the droplet:read scope.

SELECT
name,
resources
FROM digitalocean.compute.tags
WHERE tag_id = '{{ tag_id }}' -- required
;

tags_list

To list all of your tags, you can send a GET request to /v2/tags.

This endpoint will only return tagged resources that you are authorized to see
(e.g. Droplets will only be returned if you have droplet:read).

SELECT
name,
resources
FROM digitalocean.compute.tags
WHERE per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

INSERT examples

tags_create

To create a tag you can send a POST request to /v2/tags with a name attribute.

INSERT INTO digitalocean.compute.tags (
name
)
SELECT 
'{{ name }}'
RETURNING
tag
;

Manifest

# Description fields are for documentation purposes
- name: tags
props:
  - name: name
    value: "{{ name }}"
    description: |
      The name of the tag. Tags may contain letters, numbers, colons, dashes, and underscores.
      There is a limit of 255 characters per tag.
      **Note:** Tag names are case stable, which means the capitalization you use when you first create a tag is canonical.
      When working with tags in the API, you must use the tag's canonical capitalization. For example, if you create a tag named "PROD", the URL to add that tag to a resource would be `https://api.digitalocean.com/v2/tags/PROD/resources` (not `/v2/tags/prod/resources`).
      Tagged resources in the control panel will always display the canonical capitalization. For example, if you create a tag named "PROD", you can tag resources in the control panel by entering "prod". The tag will still display with its canonical capitalization, "PROD".

DELETE examples

tags_delete

A tag can be deleted by sending a DELETE request to /v2/tags/$TAG_NAME. Deleting a tag also untags all the resources that have previously been tagged by the Tag

DELETE FROM digitalocean.compute.tags
WHERE tag_id = '{{ tag_id }}' --required
;

Lifecycle Methods

tags_assign_resources

Resources can be tagged by sending a POST request to
/v2/tags/$TAG_NAME/resources with an array of json objects containing
resource_id and resource_type attributes.

Currently only tagging of Droplets, Databases, Images, Volumes, and Volume
Snapshots is supported. resource_type is expected to be the string droplet,
database, image, volume or volume_snapshot. resource_id is expected
to be the ID of the resource as a string.

In order to tag a resource, you must have both tag:create and <resource type>:update scopes. For example,
to tag a Droplet, you must have tag:create and droplet:update.

EXEC digitalocean.compute.tags.tags_assign_resources 
@tag_id='{{ tag_id }}' --required 
@@json=
'{
"resources": "{{ resources }}"
}'
;

tags_unassign_resources

Resources can be untagged by sending a DELETE request to
/v2/tags/$TAG_NAME/resources with an array of json objects containing
resource_id and resource_type attributes.

Currently only untagging of Droplets, Databases, Images, Volumes, and Volume
Snapshots is supported. resource_type is expected to be the string droplet,
database, image, volume or volume_snapshot. resource_id is expected
to be the ID of the resource as a string.

In order to untag a resource, you must have both tag:delete and <resource type>:update scopes. For example,
to untag a Droplet, you must have tag:delete and droplet:update.

EXEC digitalocean.compute.tags.tags_unassign_resources 
@tag_id='{{ tag_id }}' --required 
@@json=
'{
"resources": "{{ resources }}"
}'
;