Global Tagging | IBM Cloud API Docs

Introduction

Last updated: 2023-05-09

You can manage your tags in IBM Cloud by using the Global Tagging API. With this API, you can create, delete, search, attach, or detach tags.

Tags are uniquely identified by a Cloud Resource Naming (CRN) identifier. Tags have a name, which must be unique within a billing account. You can make tags in key:value or label format.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>global-tagging</artifactId>
	<version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:global-tagging:{version}'

Replace {version} in these examples with the release version.

View on GitHub

https://github.com/IBM/platform-services-java-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

pip install --upgrade "ibm-platform-services"

View on GitHub

https://github.com/IBM/platform-services-python-sdk

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/platform-services-go-sdk/globaltaggingv1"
)

Go get

go get -u github.com/IBM/platform-services-go-sdk/globaltaggingv1

View on GitHub

https://github.com/IBM/platform-services-go-sdk

Types of tags

The Tagging API supports three types of tag: service, user, and access.

Service tags are intended for services that want to attach a tag to a resource in an exclusive way: nobody else can go and detach it. A service tag is a privileged construct that only authorized services can manage. So, a regular user is not authorized to attach and detach service tags on a resource even if they have access to manage tags on the resource itself.

Service tags are supported only for resources that are onboarded to Global Search and Tagging, which means you cannot attach a service tag to a classic infrastructure (IMS) resource. Each resource can have a maximum of 1000 service tags.
User tags are added by an authorized user in the account. Any user with the correct access role in an account can list and can delete both service and user tags in the account as long as they are not attached to any resource. Users can delete service tags because the operation is non-disruptive in that the tags aren't attached to any resource.

The Tagging API supports multiple services assigning a tag prefix at service registration time to avoid conflicts. So, a service tag name always has the form service_prefix:tag_label. Each resource can have maximum of 1000 user tags.
Access management tags are used to manage access to resources, and they can be created in advance for use in access policies, which control access to resources where those tags will be attached. Only the account administrator can create access management tags, and they can delete them only when the tags aren't attached to any resources in the account. Only the resource administrator can attach and detach access management tags on the resource itself.

The name of an access management tag must be in the form of a key:value pair, where value cannot contain the : character. Access management tags are supported only for IAM-managed resources, which means you cannot use them to manage access to classic infrastructure (IMS) and Cloud Foundry resources. Each resource can have a maximum of 250 access tags (which is the account limit).

Filtering tags

Global Search and Tagging stores the different type of tags attached to a resource within a different attribute of the resource document:

Service tags are stored within service_tags attribute.
User tags are stored within the tags attribute.
Access management tags are stored within the access_tags attribute.

So, you can add filters to those attributes when searching for resources.

For example, the following filter matches all resources tagged with the your_service:your_tag service tag.

service_tags: "your_service:your_tag"

The following filter matches all resources that are tagged with any service tag starting with your_service:.

service_tags: "your_service:*"

The following filter matches all resources that are tagged with the my_tag user tag.

tags: "my_tag"

Finally, the following filter matches all resources that are tagged with the env:public access management tag.

access_tags: "env:public"

Endpoint URLs

The Global Tagging API uses the following public global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://tags.global-search-tagging.cloud.ibm.com

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud® private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

Private endpoint URL for VPC infrastructure (Dallas, Washington, Sydney, London, Frankfurt, Madrid, San Paulo, Tokyo, Osaka, Toronto regions): https://tags.private.global-search-tagging.cloud.ibm.com
Private endpoint URL for classic infrastructure: Dallas https://tags.private.us-south.global-search-tagging.cloud.ibm.com Sydney https://tags.private.au-syd.global-search-tagging.cloud.ibm.com London https://tags.private.eu-gb.global-search-tagging.cloud.ibm.com Frankfurt https://tags.private.eu-de.global-search-tagging.cloud.ibm.com

Example API request

curl -X POST "https://tags.global-search-tagging.cloud.ibm.com/v3/tags/attach" --header "Accept: application/json" --header "Content-Type: application/json" --header "Authorization: Bearer {IAM token}" -d '{"tag_names": ["{tagName}"], "resources": [ { "resource_id": "{resourceCRN}" } ] }'

Replace {IAM token}, {tagName} and {resourceCRN} in this example with the values for your particular API call.

Authentication

Authorization to the Global Tagging API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, --header "Authorization: Bearer <TOKEN>".

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey=<API_KEY>'

Replace <API_KEY> with your IAM API key.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_TAGGING_URL=<SERVICE_URL>
export GLOBAL_TAGGING_AUTHTYPE=iam
export GLOBAL_TAGGING_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/globaltaggingv1"
}
...
serviceClientOptions := &globaltaggingv1.GlobalTaggingV1Options{}
serviceClient, err := globaltaggingv1.NewGlobalTaggingV1UsingExternalConfig(serviceClientOptions)

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_TAGGING_URL=<SERVICE_URL>
export GLOBAL_TAGGING_AUTHTYPE=iam
export GLOBAL_TAGGING_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.global_tagging.v1.GlobalTagging;
...
GlobalTagging serviceClient = GlobalTagging.newInstance();

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_TAGGING_URL=<SERVICE_URL>
export GLOBAL_TAGGING_AUTHTYPE=iam
export GLOBAL_TAGGING_APIKEY=<API_KEY>

Example of constructing the service client

const GlobalTaggingV1 = require('@ibm-cloud/platform-services/global-tagging/v1');
...
const serviceClient = GlobalTaggingV1.newInstance({});

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_TAGGING_URL=<SERVICE_URL>
export GLOBAL_TAGGING_AUTHTYPE=iam
export GLOBAL_TAGGING_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_platform_services import GlobalTaggingV1
...
global_tagging_service = GlobalTaggingV1.new_instance()

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.

For more information about how to track tagging activity, see Auditing events for account management.

Error handling

The resource manager uses standard HTTP response codes to indicate whether a method completed successfully. A 200 type response always indicates success. A 400 type response is a failure, and a 500 type response is an internal system error.

HTTP error code	Description	Recovery
`200`	Success	The request was successful.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`404`	Not Found	The requested resource could not be found.
`409`	Conflict	The entity is already in the requested state.
`410`	Gone	The resource is valid but has been removed already in a previous call
`500`	Internal Server Error	offering_name is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

After tagging resources, you can search for them by the tag name or resource groups or building even more complex search strings. For more information about advanced search capabilities that use the Lucene query syntax, see the Global Search API.

Lists all tags that are in a billing account. Use the attached_to parameter to return the list of tags that are attached to the specified resource.

GET /v3/tags

(globalTagging *GlobalTaggingV1) ListTags(listTagsOptions *ListTagsOptions) (result *TagList, response *core.DetailedResponse, err error)

(globalTagging *GlobalTaggingV1) ListTagsWithContext(ctx context.Context, listTagsOptions *ListTagsOptions) (result *TagList, response *core.DetailedResponse, err error)

ServiceCall<TagList> listTags(ListTagsOptions listTagsOptions)

listTags(params)

list_tags(
        self,
        *,
        transaction_id: str = None,
        impersonate_user: str = None,
        account_id: str = None,
        tag_type: str = None,
        full_data: bool = None,
        providers: List[str] = None,
        attached_to: str = None,
        offset: int = None,
        limit: int = None,
        timeout: int = None,
        order_by_name: str = None,
        attached_only: bool = None,
        **kwargs,
    ) -> DetailedResponse

Request

Instantiate the ListTagsOptions struct and set the fields to provide parameter values for the ListTags method.

Use the ListTagsOptions.Builder to create a ListTagsOptions object that contains the parameter values for the listTags method.

Custom Headers

X-IMS-Auth-Token
string
The infrastructure authentication token, which can be used for searching the infrastructure tags. It is deprecated in favor of IAM authentication token.

Possible values: Value must match regular expression ^Basic .*$
x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

account_id
string
The ID of the billing account to list the tags for. If it is not set, then it is taken from the authorization token. This parameter is required if tag_type is set to service.

Possible values: Value must match regular expression ^[a-fA-F0-9]{32}$
tag_type
string
The type of the tag you want to list. Supported values are user, service and access.

Allowable values: [user,service,access]
Default: user
full_data
boolean
If set to true, this query returns the provider, ghost, ims or ghost,ims, where the tag exists and the number of attached resources.

Default: false
providers
string[]
Select a provider. Supported values are ghost and ims. To list both Global Search and Tagging tags and infrastructure tags, use ghost,ims. service and access tags can only be attached to resources that are onboarded to Global Search and Tagging, so you should not set this parameter to list them.

Allowable values: [ghost,ims]
Default: ["ghost"]
attached_to
string
If you want to return only the list of tags that are attached to a specified resource, pass the ID of the resource on this parameter. For resources that are onboarded to Global Search and Tagging, the resource ID is the CRN; for IMS resources, it is the IMS ID. When using this parameter, you must specify the appropriate provider (ims or ghost).

Possible values: Value must match regular expression ^crn:v1(:[^:]*){8}|[0-9]+$
offset
integer
The offset is the index of the item from which you want to start returning data from.

Possible values: value ≥ 0
Default: 0
limit
integer
The number of tags to return.

Possible values: 1 ≤ value ≤ 1000
Default: 100
timeout
integer
The timeout in milliseconds, bounds the request to run within the specified time value. It returns the accumulated results until time runs out.

Possible values: 0 ≤ value ≤ 600000
Default: 0
order_by_name
string
Order the output by tag name.

Allowable values: [asc,desc]
Default: asc
attached_only
boolean
Filter on attached tags. If true, it returns only tags that are attached to one or more resources. If false, it returns all tags.

Default: false

parameter

WithContext method only

ListTagsOptions

The ListTags options.

ListTagsOptions

The listTags options.

parameters

transactionId
string
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
impersonateUser
string
The user on whose behalf the get operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
accountId
string
The ID of the billing account to list the tags for. If it is not set, then it is taken from the authorization token. This parameter is required if tag_type is set to service.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$/
tagType
string
The type of the tag you want to list. Supported values are user, service and access.

Allowable values: [user,service,access]
Default: user
fullData
boolean
If set to true, this query returns the provider, ghost, ims or ghost,ims, where the tag exists and the number of attached resources.

Default: false
providers
string[]
Select a provider. Supported values are ghost and ims. To list both Global Search and Tagging tags and infrastructure tags, use ghost,ims. service and access tags can only be attached to resources that are onboarded to Global Search and Tagging, so you should not set this parameter to list them.

Allowable values: [ghost,ims]
Default: ["ghost"]
attachedTo
string
If you want to return only the list of tags that are attached to a specified resource, pass the ID of the resource on this parameter. For resources that are onboarded to Global Search and Tagging, the resource ID is the CRN; for IMS resources, it is the IMS ID. When using this parameter, you must specify the appropriate provider (ims or ghost).

Possible values: Value must match regular expression /^crn:v1(:[^:]*){8}|[0-9]+$/
offset
number
The offset is the index of the item from which you want to start returning data from.

Possible values: value ≥ 0
Default: 0
limit
number
The number of tags to return.

Possible values: 1 ≤ value ≤ 1000
Default: 100
timeout
number
The timeout in milliseconds, bounds the request to run within the specified time value. It returns the accumulated results until time runs out.

Possible values: 0 ≤ value ≤ 600000
Default: 0
orderByName
string
Order the output by tag name.

Allowable values: [asc,desc]
Default: asc
attachedOnly
boolean
Filter on attached tags. If true, it returns only tags that are attached to one or more resources. If false, it returns all tags.

Default: false

parameters

transaction_id
str
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
impersonate_user
str
The user on whose behalf the get operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
account_id
str
The ID of the billing account to list the tags for. If it is not set, then it is taken from the authorization token. This parameter is required if tag_type is set to service.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$/
tag_type
str
The type of the tag you want to list. Supported values are user, service and access.

Allowable values: [user,service,access]
Default: user
full_data
bool
If set to true, this query returns the provider, ghost, ims or ghost,ims, where the tag exists and the number of attached resources.

Default: false
providers
List[str]
Select a provider. Supported values are ghost and ims. To list both Global Search and Tagging tags and infrastructure tags, use ghost,ims. service and access tags can only be attached to resources that are onboarded to Global Search and Tagging, so you should not set this parameter to list them.

Allowable values: [ghost,ims]
Default: ["ghost"]
attached_to
str
If you want to return only the list of tags that are attached to a specified resource, pass the ID of the resource on this parameter. For resources that are onboarded to Global Search and Tagging, the resource ID is the CRN; for IMS resources, it is the IMS ID. When using this parameter, you must specify the appropriate provider (ims or ghost).

Possible values: Value must match regular expression /^crn:v1(:[^:]*){8}|[0-9]+$/
offset
int
The offset is the index of the item from which you want to start returning data from.

Possible values: value ≥ 0
Default: 0
limit
int
The number of tags to return.

Possible values: 1 ≤ value ≤ 1000
Default: 100
timeout
int
The timeout in milliseconds, bounds the request to run within the specified time value. It returns the accumulated results until time runs out.

Possible values: 0 ≤ value ≤ 600000
Default: 0
order_by_name
str
Order the output by tag name.

Allowable values: [asc,desc]
Default: asc
attached_only
bool
Filter on attached tags. If true, it returns only tags that are attached to one or more resources. If false, it returns all tags.

Default: false

Example request

curl -X GET --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v3/tags?tag_type=user&attached_only=true&full_data=true&providers=ghost&offset=0&limit=10&order_by_name=asc"

Example request

listTagsOptions := globalTaggingService.NewListTagsOptions()
listTagsOptions.SetTagType("user")
listTagsOptions.SetAttachedOnly(true)
listTagsOptions.SetFullData(true)
listTagsOptions.SetProviders([]string{"ghost"})
listTagsOptions.SetOrderByName("asc")

tagList, response, err := globalTaggingService.ListTags(listTagsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(tagList, "", "  ")
fmt.Println(string(b))

Example request

ListTagsOptions listTagsOptions = new ListTagsOptions.Builder()
    .tagType("user")
    .attachedOnly(true)
    .fullData(true)
    .addProviders("ghost")
    .orderByName("asc")
    .build();

Response<TagList> response = service.listTags(listTagsOptions).execute();
TagList tagList = response.getResult();
System.out.println(tagList.toString());

Example request

const params = {
  tagType: 'user',
  attachedOnly: true,
  fullData: true,
  providers: ['ghost'],
  orderByName: 'asc',
};

globalTaggingService.listTags(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

tag_list = global_tagging_service.list_tags(
  tag_type='user',
  attached_only=True,
  full_data=True,
  providers=['ghost'],
  order_by_name='asc').get_result()

print(json.dumps(tag_list, indent=2))

Response Body

TagList

A list of tags.

TagList

A list of tags.

TagList

A list of tags.

TagList

A list of tags.

TagList

A list of tags.

Status Code

200
A result paging with the list of tags that match the provided filters.
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token not valid
407
Unsupported operation
429
Too Many Requests
500
Internal server error, IAM not initialized, or malformed IAM credentials
default
System problem or unexpected error

No Sample Response

This method does not specify any sample responses.

Create an access management tag. To create an access tag, you must have the access listed in the Granting users access to tag resources documentation. service and user tags cannot be created upfront. They are created when they are attached for the first time to a resource.

POST /v3/tags

(globalTagging *GlobalTaggingV1) CreateTag(createTagOptions *CreateTagOptions) (result *CreateTagResults, response *core.DetailedResponse, err error)

(globalTagging *GlobalTaggingV1) CreateTagWithContext(ctx context.Context, createTagOptions *CreateTagOptions) (result *CreateTagResults, response *core.DetailedResponse, err error)

ServiceCall<CreateTagResults> createTag(CreateTagOptions createTagOptions)

createTag(params)

create_tag(
        self,
        tag_names: List[str],
        *,
        impersonate_user: str = None,
        transaction_id: str = None,
        account_id: str = None,
        tag_type: str = None,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

This action applies only to access management tags.

ghost-tags.create-access-tag

Auditing

Calling this method generates the following auditing event.

global-search-tagging.tag.create

Request

Instantiate the CreateTagOptions struct and set the fields to provide parameter values for the CreateTag method.

Use the CreateTagOptions.Builder to create a CreateTagOptions object that contains the parameter values for the createTag method.

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

account_id
string
The ID of the billing account where the tag must be created.

Possible values: Value must match regular expression ^[a-fA-F0-9]{32}
tag_type
string
The type of the tags you want to create. The only allowed value is access.

Allowable values: [access]
Default: access

Request Body

Required*

CreateTagBody

An array of access management tags to be created.

parameter

WithContext method only

CreateTagOptions

The CreateTag options.

CreateTagOptions

The createTag options.

parameters

tagNames
Required*
string[]
An array of tag names to create.

Possible values: 1 ≤ number of items ≤ 100, length ≤ 128, Value must match regular expression /^([ ]*[A-Za-z0-9:_.-]+[ ]*)+$/
impersonateUser
string
The user on whose behalf the create operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
transactionId
string
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
accountId
string
The ID of the billing account where the tag must be created. It is a required parameter if impersonate_user is set.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tagType
string
The type of the tags you want to create. The only allowed value is access.

Allowable values: [access]
Default: access

parameters

tag_names
Required*
List[str]
An array of tag names to create.

Possible values: 1 ≤ number of items ≤ 100, length ≤ 128, Value must match regular expression /^([ ]*[A-Za-z0-9:_.-]+[ ]*)+$/
impersonate_user
str
The user on whose behalf the create operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
transaction_id
str
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
account_id
str
The ID of the billing account where the tag must be created. It is a required parameter if impersonate_user is set.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tag_type
str
The type of the tags you want to create. The only allowed value is access.

Allowable values: [access]
Default: access

Example request

curl -X POST --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   -d '{ "tag_names": ["env:example-access-tag"] }'   "{base_url}/v3/tags?tag_type=access"

Example request

createTagOptions := globalTaggingService.NewCreateTagOptions(
  []string{"env:example-access-tag"},
)
createTagOptions.SetTagType("access")

createTagResults, response, err := globalTaggingService.CreateTag(createTagOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(createTagResults, "", "  ")
fmt.Println(string(b))

Example request

CreateTagOptions createTagOptions = new CreateTagOptions.Builder()
    .addTagNames("env:example-access-tag")
    .tagType("access")
    .build();

Response<CreateTagResults> response = service.createTag(createTagOptions).execute();
CreateTagResults createTagResults = response.getResult();
System.out.println(createTagResults);

Example request

const params = {
  tagNames: ['env:example-access-tag'],
  tagType: 'access',
};

globalTaggingService.createTag(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

create_tag_results = global_tagging_service.create_tag(
  tag_names=['env:example-access-tag'],
  tag_type='access').get_result()

print(json.dumps(create_tag_results, indent=2))

Response

Response Body

CreateTagResults

Results of a create tag(s) request.

CreateTagResults

Results of a create tag(s) request.

CreateTagResults

Results of a create tag(s) request.

CreateTagResults

Results of a create tag(s) request.

CreateTagResults

Results of a create tag(s) request.

Status Code

200
The tag was created successfully.
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
429
Too Many Requests
default
System problem or unexpected error.

No Sample Response

This method does not specify any sample responses.

Delete the tags that are not attached to any resource.

DELETE /v3/tags

(globalTagging *GlobalTaggingV1) DeleteTagAll(deleteTagAllOptions *DeleteTagAllOptions) (result *DeleteTagsResult, response *core.DetailedResponse, err error)

(globalTagging *GlobalTaggingV1) DeleteTagAllWithContext(ctx context.Context, deleteTagAllOptions *DeleteTagAllOptions) (result *DeleteTagsResult, response *core.DetailedResponse, err error)

ServiceCall<DeleteTagsResult> deleteTagAll(DeleteTagAllOptions deleteTagAllOptions)

deleteTagAll(params)

delete_tag_all(
        self,
        *,
        transaction_id: str = None,
        providers: str = None,
        impersonate_user: str = None,
        account_id: str = None,
        tag_type: str = None,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

This action applies only to access management tags.

ghost-tags.delete-access-tag

Auditing

Calling this method generates the following auditing event.

global-search-tagging.tags.delete

Request

Instantiate the DeleteTagAllOptions struct and set the fields to provide parameter values for the DeleteTagAll method.

Use the DeleteTagAllOptions.Builder to create a DeleteTagAllOptions object that contains the parameter values for the deleteTagAll method.

Custom Headers

X-IMS-Auth-Token
string
The infrastructure authentication token, which can be used for for deleting the infrastructure tags. It is deprecated in favor of IAM authentication token.

Possible values: Value must match regular expression ^Basic .*$
x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

providers
string
Select a provider. Supported values are ghost and ims.

Allowable values: [ghost,ims]
Default: ghost
account_id
string
The ID of the billing account to delete the tags for. If it is not set, then it is taken from the authorization token. It is a required parameter if tag_type is set to service.

Possible values: Value must match regular expression ^[a-fA-F0-9]{32}
tag_type
string
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources (providers parameter set to ims).

Allowable values: [user,service,access]
Default: user

parameter

WithContext method only

DeleteTagAllOptions

The DeleteTagAll options.

DeleteTagAllOptions

The deleteTagAll options.

parameters

transactionId
string
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
providers
string
Select a provider. Supported values are ghost and ims.

Allowable values: [ghost,ims]
Default: ghost
impersonateUser
string
The user on whose behalf the delete all operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
accountId
string
The ID of the billing account to delete the tags for. If it is not set, then it is taken from the authorization token. It is a required parameter if tag_type is set to service.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tagType
string
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources (providers parameter set to ims).

Allowable values: [user,service,access]
Default: user

parameters

transaction_id
str
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
providers
str
Select a provider. Supported values are ghost and ims.

Allowable values: [ghost,ims]
Default: ghost
impersonate_user
str
The user on whose behalf the delete all operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
account_id
str
The ID of the billing account to delete the tags for. If it is not set, then it is taken from the authorization token. It is a required parameter if tag_type is set to service.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tag_type
str
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources (providers parameter set to ims).

Allowable values: [user,service,access]
Default: user

Example request

curl -X DELETE --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   "{base_url}/v3/tags?tag_type=user"

Example request

deleteTagAllOptions := globalTaggingService.NewDeleteTagAllOptions()
deleteTagAllOptions.SetTagType("user")

deleteTagsResult, response, err := globalTaggingService.DeleteTagAll(deleteTagAllOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(deleteTagsResult, "", "  ")
fmt.Println(string(b))

Example request

DeleteTagAllOptions deleteTagAllOptions = new DeleteTagAllOptions.Builder()
    .tagType("user")
    .build();

Response<DeleteTagsResult> response = service.deleteTagAll(deleteTagAllOptions).execute();
DeleteTagsResult deleteTagsResult = response.getResult();

System.out.println(deleteTagsResult.toString());

Example request

const params = {
  tagType: 'access',
};

globalTaggingService.deleteTagAll(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

delete_tags_result = global_tagging_service.delete_tag_all(
  tag_type='user').get_result()

print(json.dumps(delete_tags_result, indent=2))

Response

Response Body

DeleteTagsResult

Results of deleting unattatched tags.

DeleteTagsResult

Results of deleting unattatched tags.

DeleteTagsResult

Results of deleting unattatched tags.

DeleteTagsResult

Results of deleting unattatched tags.

DeleteTagsResult

Results of deleting unattatched tags.

Status Code

200
A results page that includes the list of tags that have been deleted.
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
429
Too Many Requests
default
System problem or unexpected error

No Sample Response

This method does not specify any sample responses.

Delete an existing tag. A tag can be deleted only if it is not attached to any resource.

DELETE /v3/tags/{tag_name}

(globalTagging *GlobalTaggingV1) DeleteTag(deleteTagOptions *DeleteTagOptions) (result *DeleteTagResults, response *core.DetailedResponse, err error)

(globalTagging *GlobalTaggingV1) DeleteTagWithContext(ctx context.Context, deleteTagOptions *DeleteTagOptions) (result *DeleteTagResults, response *core.DetailedResponse, err error)

ServiceCall<DeleteTagResults> deleteTag(DeleteTagOptions deleteTagOptions)

deleteTag(params)

delete_tag(
        self,
        tag_name: str,
        *,
        transaction_id: str = None,
        providers: List[str] = None,
        impersonate_user: str = None,
        account_id: str = None,
        tag_type: str = None,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

This action applies only to access management tags.

ghost-tags.delete-access-tag

Auditing

Calling this method generates the following auditing event.

global-search-tagging.tag.delete

Request

Instantiate the DeleteTagOptions struct and set the fields to provide parameter values for the DeleteTag method.

Use the DeleteTagOptions.Builder to create a DeleteTagOptions object that contains the parameter values for the deleteTag method.

Custom Headers

X-IMS-Auth-Token
string
The infrastructure authentication token, which can be used for for deleting an infrastructure tag. It is deprecated in favor of IAM authentication token.

Possible values: Value must match regular expression ^Basic .*$
x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Path Parameters

tag_name
Required*
string
The name of tag to be deleted.

Possible values: length ≤ 128, Value must match regular expression ^[A-Za-z0-9:_ .-]+$

Query Parameters

providers
string[]
Select a provider. Supported values are ghost and ims. To delete tags both in Global Search and Tagging and in IMS, use ghost,ims

Allowable values: [ghost,ims]
Default: ["ghost"]
account_id
string
The ID of the billing account to delete the tag for. It is a required parameter if tag_type is set to service, otherwise it is inferred from the authorization IAM token.

Possible values: Value must match regular expression ^[a-fA-F0-9]{32}
tag_type
string
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources (providers parameter set to ims).

Allowable values: [user,service,access]
Default: user

parameter

WithContext method only

DeleteTagOptions

The DeleteTag options.

DeleteTagOptions

The deleteTag options.

parameters

tagName
Required*
string
The name of tag to be deleted.

Possible values: length ≤ 128, Value must match regular expression /^[A-Za-z0-9:_ .-]+$/
transactionId
string
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
providers
string[]
Select a provider. Supported values are ghost and ims. To delete tags both in Global Search and Tagging and in IMS, use ghost,ims.

Allowable values: [ghost,ims]
Default: ["ghost"]
impersonateUser
string
The user on whose behalf the delete operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
accountId
string
The ID of the billing account to delete the tag for. It is a required parameter if tag_type is set to service, otherwise it is inferred from the authorization IAM token.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tagType
string
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources (providers parameter set to ims).

Allowable values: [user,service,access]
Default: user

parameters

tag_name
Required*
str
The name of tag to be deleted.

Possible values: length ≤ 128, Value must match regular expression /^[A-Za-z0-9:_ .-]+$/
transaction_id
str
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
providers
List[str]
Select a provider. Supported values are ghost and ims. To delete tags both in Global Search and Tagging and in IMS, use ghost,ims.

Allowable values: [ghost,ims]
Default: ["ghost"]
impersonate_user
str
The user on whose behalf the delete operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
account_id
str
The ID of the billing account to delete the tag for. It is a required parameter if tag_type is set to service, otherwise it is inferred from the authorization IAM token.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tag_type
str
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources (providers parameter set to ims).

Allowable values: [user,service,access]
Default: user

Example request

    curl -X DELETE --header "Authorization: Bearer {iam_token}" --header "Accept: application/json" "{base_url}/v3/tags/{tag_name}?tag_type=access"

Example request

deleteTagOptions := globalTaggingService.NewDeleteTagOptions("env:example-access-tag")
deleteTagOptions.SetTagType("access")

deleteTagResults, response, err := globalTaggingService.DeleteTag(deleteTagOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(deleteTagResults, "", "  ")
fmt.Println(string(b))

Example request

DeleteTagOptions deleteTagOptions = new DeleteTagOptions.Builder()
    .tagName("env:example-access-tag")
    .tagType("access")
    .build();

Response<DeleteTagResults> response = service.deleteTag(deleteTagOptions).execute();
DeleteTagResults deleteTagResults = response.getResult();
System.out.println(deleteTagResults.toString());

Example request

const params = {
  tagName: 'env:example-access-tag',
  tagType: 'access',
};

globalTaggingService.deleteTag(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

delete_tag_results = global_tagging_service.delete_tag(
  tag_name='env:example-access-tag',
  tag_type='access').get_result()

print(json.dumps(delete_tag_results, indent=2))

Response

Response Body

DeleteTagResults

Results of a delete_tag request.

DeleteTagResults

Results of a delete_tag request.

DeleteTagResults

Results of a delete_tag request.

DeleteTagResults

Results of a delete_tag request.

DeleteTagResults

Results of a delete_tag request.

Status Code

200
Success message
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
429
Too Many Requests
default
System problem or unexpected error

No Sample Response

This method does not specify any sample responses.

Attaches one or more tags to one or more resources. Each resource can have no more than 1000 tags per each 'user' and 'service' type, and no more than 250 'access' tags (which is the account limit).

POST /v3/tags/attach

(globalTagging *GlobalTaggingV1) AttachTag(attachTagOptions *AttachTagOptions) (result *TagResults, response *core.DetailedResponse, err error)

(globalTagging *GlobalTaggingV1) AttachTagWithContext(ctx context.Context, attachTagOptions *AttachTagOptions) (result *TagResults, response *core.DetailedResponse, err error)

ServiceCall<TagResults> attachTag(AttachTagOptions attachTagOptions)

attachTag(params)

attach_tag(
        self,
        resources: List['Resource'],
        *,
        tag_name: str = None,
        tag_names: List[str] = None,
        transaction_id: str = None,
        impersonate_user: str = None,
        account_id: str = None,
        tag_type: str = None,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

This action applies only to user tags. Because service tags are managed by IBM services. IAM actions do not apply to them.

To attach a user tag on a resource, you must have the access listed in the Granting users access to tag resources documentation.

To attach a service tag, you must be an authorized service. If that is the case, then you can attach a service tag with your registered prefix to any resource in any account. The account ID must be set through the account_id query parameter.

To attach an access tag, you must be the resource administrator within the account. You can attach only access tags that already exist.

In the case you want to replace all the list of user tags attached, you must have both the accesses to attach and detach user tags to the resource.

In the case you want to replace all the list of access tags attached, you must have both the accesses to attach and detach access tags to the resource.

global-search-tagging.tag.attach-user-tag
global-search-tagging.tag.attach-access-tag
global-search-tagging.tag.detach-user-tag
global-search-tagging.tag.detach-access-tag

Auditing

Calling this method generates the following auditing event.

<serviceName>.tag.attach

Request

Instantiate the AttachTagOptions struct and set the fields to provide parameter values for the AttachTag method.

Use the AttachTagOptions.Builder to create a AttachTagOptions object that contains the parameter values for the attachTag method.

Custom Headers

X-IMS-Auth-Token
string
The infrastructure authentication token, which can be used for attaching an infrastructure tag. It is deprecated in favor of IAM authentication token.

Possible values: Value must match regular expression ^Basic .*$
creator-iam-id
string
The user on whose behalf the attach operation must be performed (for administrators only).

Possible values: Value must match regular expression ^[a-zA-Z0-9_,-]*$
created-at
string
The time when the tag creation must be recorded (for administrators only).

Possible values: Value must match regular expression \d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[1-2]\d|3[0-1])T(?:[0-1]\d|2[0-3]):[0-5]\d:[0-5]\d.\d{3}Z|\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[1-2]\d|3[0-1])T(?:[0-1]\d|2[0-3]):[0-5]\d:[0-5]\dZ
x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

account_id
string
The ID of the billing account of the tagged resource. It is a required parameter if tag_type is set to service. Otherwise, it is inferred from the authorization IAM token.

Possible values: Value must match regular expression ^[a-fA-F0-9]{32}
tag_type
string
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources.

Allowable values: [user,service,access]
Default: user
replace
boolean
Flag to request replacement of all attached tags. Set 'true' if you want to replace all the list of tags attached to the resource. Default value is false.

Default: false

Request Body

Required*

AttachTagRequest

Array of tag names and list of resource IDs on which the tags should be attached. For resources that are onboarded to Global Search and Tagging, the resource ID is the CRN; for IMS resources, it is the IMS ID. The maximum number of resource IDs where the tag will be attached is 100. You can specify up to 100 tags to be attached.

Examples:

View

parameter

WithContext method only

AttachTagOptions

The AttachTag options.

AttachTagOptions

The attachTag options.

parameters

resources
Required*
List of resources on which the tag or tags are attached.

Possible values: 1 ≤ number of items ≤ 100
tagName
string
The name of the tag to attach.

Possible values: length ≤ 128, Value must match regular expression /^([ ]*[A-Za-z0-9:_.-]+[ ]*)+$/
tagNames
string[]
An array of tag names to attach.

Possible values: 1 ≤ number of items ≤ 100, length ≤ 128, Value must match regular expression /^([ ]*[A-Za-z0-9:_.-]+[ ]*)+$/
transactionId
string
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
impersonateUser
string
The user on whose behalf the attach operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
accountId
string
The ID of the billing account of the tagged resource. It is a required parameter if tag_type is set to service. Otherwise, it is inferred from the authorization IAM token.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tagType
string
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources.

Allowable values: [user,service,access]
Default: user

parameters

resources
Required*
List of resources on which the tag or tags are attached.

Possible values: 1 ≤ number of items ≤ 100
tag_name
str
The name of the tag to attach.

Possible values: length ≤ 128, Value must match regular expression /^([ ]*[A-Za-z0-9:_.-]+[ ]*)+$/
tag_names
List[str]
An array of tag names to attach.

Possible values: 1 ≤ number of items ≤ 100, length ≤ 128, Value must match regular expression /^([ ]*[A-Za-z0-9:_.-]+[ ]*)+$/
transaction_id
str
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
impersonate_user
str
The user on whose behalf the attach operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
account_id
str
The ID of the billing account of the tagged resource. It is a required parameter if tag_type is set to service. Otherwise, it is inferred from the authorization IAM token.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tag_type
str
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources.

Allowable values: [user,service,access]
Default: user

Example request

    curl -X POST --header "Authorization: Bearer {iam_token}" --header "Accept: application/json" --header "Content-Type: application/json" -d '{ "resources": [{ "resource_id": "{RESOURCE_CRN}" }], "tag_names": ["tag_test_1", "tag_test_2"] }' "{base_url}/v3/tags/attach?tag_type=user"

Example request

resourceModel := &globaltaggingv1.Resource{
  ResourceID: &resourceCRN,
}

attachTagOptions := globalTaggingService.NewAttachTagOptions(
  []globaltaggingv1.Resource{*resourceModel},
)
attachTagOptions.SetTagNames([]string{"tag_test_1", "tag_test_2"})
attachTagOptions.SetTagType("user")

tagResults, response, err := globalTaggingService.AttachTag(attachTagOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(tagResults, "", "  ")
fmt.Println(string(b))

Example request

Resource resourceModel = new Resource.Builder().resourceId(resourceCRN).build();
AttachTagOptions attachTagOptions = new AttachTagOptions.Builder()
    .addResources(resourceModel)
    .addTagNames("tag_test_1")
    .addTagNames("tag_test_2")
    .build();

Response<TagResults> response = service.attachTag(attachTagOptions).execute();
TagResults tagResults = response.getResult();
System.out.println(tagResults.toString());

Example request

const resourceModel = {
  resource_id: resourceCrn,
};

const params = {
  resources: [resourceModel],
  tagNames: ["tag_test_1", "tag_test_2"],
  tagType: 'user',
};

globalTaggingService.attachTag(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

resource_model = {'resource_id': resource_crn}

tag_results = global_tagging_service.attach_tag(
  resources=[resource_model],
  tag_names=['tag_test_1', 'tag_test_2'],
  tag_type='user').get_result()

print(json.dumps(tag_results, indent=2))

Response

Response Body

TagResults

Results of an attach_tag or detach_tag request

TagResults

Results of an attach_tag or detach_tag request.

Examples:

View

TagResults

Results of an attach_tag or detach_tag request.

Examples:

View

TagResults

Results of an attach_tag or detach_tag request.

Examples:

View

TagResults

Results of an attach_tag or detach_tag request.

Examples:

View

Status Code

200
The array of tag attach operations result
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
429
Too Many Requests
default
System problem or unexpected error

Example responses

Status 200

{
  "results": [
    {
      "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1c061f4485b34360a8f8ee049880dc13",
      "is_error": false
    },
    {
      "resource_id": "58546459",
      "resource_type": "NETWORK_VLAN_FIREWALL",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint",
      "code": "GST915E",
      "level": "error",
      "httpCode": 401,
      "more_info": "IMS token is missing"
    }
  ]
}

Success example

{
  "results": [
    {
      "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1c061f4485b34360a8f8ee049880dc13",
      "is_error": false
    },
    {
      "resource_id": "58546459",
      "resource_type": "NETWORK_VLAN_FIREWALL",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint",
      "code": "GST915E",
      "level": "error",
      "httpCode": 401,
      "more_info": "IMS token is missing"
    }
  ]
}

Detaches one or more tags from one or more resources.

POST /v3/tags/detach

(globalTagging *GlobalTaggingV1) DetachTag(detachTagOptions *DetachTagOptions) (result *TagResults, response *core.DetailedResponse, err error)

(globalTagging *GlobalTaggingV1) DetachTagWithContext(ctx context.Context, detachTagOptions *DetachTagOptions) (result *TagResults, response *core.DetailedResponse, err error)

ServiceCall<TagResults> detachTag(DetachTagOptions detachTagOptions)

detachTag(params)

detach_tag(
        self,
        resources: List['Resource'],
        *,
        tag_name: str = None,
        tag_names: List[str] = None,
        transaction_id: str = None,
        impersonate_user: str = None,
        account_id: str = None,
        tag_type: str = None,
        **kwargs,
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access.

This action applies only to user tags. Because service tags are managed by IBM services, IAM actions do not apply to them.

To detach a user tag on a resource you must have the permissions listed in the Granting users access to tag resources documentation.

To detach a service tag, you must be an authorized Service. If that is the case, then you can detach a service tag with your registered prefix from any resource in any account. The account ID must be set through the account_id query parameter.

To detach an access tag, you must be the resource administrator within the account.

global-search-tagging.tag.detach-user-tag
global-search-tagging.tag.detach-access-tag

Auditing

Calling this method generates the following auditing event.

<serviceName>.tag.detach

Request

Instantiate the DetachTagOptions struct and set the fields to provide parameter values for the DetachTag method.

Use the DetachTagOptions.Builder to create a DetachTagOptions object that contains the parameter values for the detachTag method.

Custom Headers

X-IMS-Auth-Token
string
The infrastructure authentication token, which can be used for detaching an infrastructure tag. It is deprecated in favor of IAM authentication token.

Possible values: Value must match regular expression ^Basic .*$
x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

account_id
string
The ID of the billing account of the untagged resource. It is a required parameter if tag_type is set to service, otherwise it is inferred from the authorization IAM token.

Possible values: Value must match regular expression ^[a-fA-F0-9]{32}
tag_type
string
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources.

Allowable values: [user,service,access]
Default: user

Request Body

Required*

DetachTagRequest

Array of tag names and list of resource IDs from which the tag should be detached. For resources that are onboarded to Global Search and Tagging, the resource ID is the CRN; for IMS resources, it is the IMS ID. For IMS resource also the IMS data type must be specified. The maximum number of resources where the tag will be detached from is 100. You can specify up to 100 tags to be detached.

Examples:

View

parameter

WithContext method only

DetachTagOptions

The DetachTag options.

DetachTagOptions

The detachTag options.

parameters

resources
Required*
List of resources on which the tag or tags are detached.

Possible values: 1 ≤ number of items ≤ 100
tagName
string
The name of the tag to detach.

Possible values: length ≤ 128, Value must match regular expression /^[A-Za-z0-9:_ .-]+$|^[*]{1}$/
tagNames
string[]
An array of tag names to detach.

Possible values: 1 ≤ number of items ≤ 100, length ≤ 128, Value must match regular expression /^[A-Za-z0-9:_ .-]+$/
transactionId
string
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
impersonateUser
string
The user on whose behalf the detach operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
accountId
string
The ID of the billing account of the untagged resource. It is a required parameter if tag_type is set to service, otherwise it is inferred from the authorization IAM token.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tagType
string
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources.

Allowable values: [user,service,access]
Default: user

parameters

resources
Required*
List of resources on which the tag or tags are detached.

Possible values: 1 ≤ number of items ≤ 100
tag_name
str
The name of the tag to detach.

Possible values: length ≤ 128, Value must match regular expression /^[A-Za-z0-9:_ .-]+$|^[*]{1}$/
tag_names
List[str]
An array of tag names to detach.

Possible values: 1 ≤ number of items ≤ 100, length ≤ 128, Value must match regular expression /^[A-Za-z0-9:_ .-]+$/
transaction_id
str
An alphanumeric string that can be used to trace a request across services. If not specified, it automatically generated with the prefix "gst-".

Possible values: 1 ≤ length ≤ 150, Value must match regular expression /.*/
impersonate_user
str
The user on whose behalf the detach operation must be performed (for administrators only).

Possible values: Value must match regular expression /^.*-.*$/
account_id
str
The ID of the billing account of the untagged resource. It is a required parameter if tag_type is set to service, otherwise it is inferred from the authorization IAM token.

Possible values: Value must match regular expression /^[a-zA-Z0-9.]+$|^[*]{1}$/
tag_type
str
The type of the tag. Supported values are user, service and access. service and access are not supported for IMS resources.

Allowable values: [user,service,access]
Default: user

Example request

curl -X POST --header "Authorization: Bearer {iam_token}"   --header "Accept: application/json"   --header "Content-Type: application/json"   -d '{ "resources": [{ "resource_id": "{RESOURCE_CRN}" }], "tag_names": ["tag_test_1", "tag_test_2"] }'   "{base_url}/v3/tags/detach?tag_type=user"

Example request

resourceModel := &globaltaggingv1.Resource{
  ResourceID: &resourceCRN,
}

detachTagOptions := globalTaggingService.NewDetachTagOptions(
  []globaltaggingv1.Resource{*resourceModel},
)
detachTagOptions.SetTagNames([]string{"tag_test_1", "tag_test_2"})
detachTagOptions.SetTagType("user")

tagResults, response, err := globalTaggingService.DetachTag(detachTagOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(tagResults, "", "  ")
fmt.Println(string(b))

Example request

Resource resourceModel = new Resource.Builder().resourceId(resourceCRN).build();
DetachTagOptions detachTagOptions = new DetachTagOptions.Builder()
    .addResources(resourceModel)
    .addTagNames("tag_test_1")
    .addTagNames("tag_test_2")
    .tagType("user")
    .build();

Response<TagResults> response = service.detachTag(detachTagOptions).execute();
TagResults tagResults = response.getResult();
System.out.println(tagResults.toString());

Example request

const resourceModel = {
  resource_id: resourceCrn,
};

const params = {
  resources: [resourceModel],
  tagNames: ["tag_test_1", "tag_test_2"],
  tagType: 'user',
};

globalTaggingService.detachTag(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

resource_model = {'resource_id': resource_crn}

tag_results = global_tagging_service.detach_tag(
  resources=[resource_model],
  tag_names=['tag_test_1', 'tag_test_2'],
  tag_type='user').get_result()

print(json.dumps(tag_results, indent=2))

Response

Response Body

TagResults

Results of an attach_tag or detach_tag request

TagResults

Results of an attach_tag or detach_tag request.

Examples:

View

TagResults

Results of an attach_tag or detach_tag request.

Examples:

View

TagResults

Results of an attach_tag or detach_tag request.

Examples:

View

TagResults

Results of an attach_tag or detach_tag request.

Examples:

View

Status Code

200
The array of tag detach operations results.
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
429
Too Many Requests
default
System problem or unexpected error

Example responses

Status 200

{
  "results": [
    {
      "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1c061f4485b34360a8f8ee049880dc13",
      "is_error": false
    },
    {
      "resource_id": "58546459",
      "resource_type": "NETWORK_VLAN_FIREWALL",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint",
      "code": "GST915E",
      "level": "error",
      "httpCode": 401,
      "more_info": "IMS token is missing"
    }
  ]
}

Success example

{
  "results": [
    {
      "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1c061f4485b34360a8f8ee049880dc13",
      "is_error": false
    },
    {
      "resource_id": "58546459",
      "resource_type": "NETWORK_VLAN_FIREWALL",
      "is_error": true,
      "response": "IMS_API_ERROR",
      "message": "Error calling IMS REST API endpoint",
      "code": "GST915E",
      "level": "error",
      "httpCode": 401,
      "more_info": "IMS token is missing"
    }
  ]
}

Tag one resource by passing in one or more tags. Tag references are cleared out every time this operation is called. If your resource is already tagged, you need to pass the current tags along with any new ones. To remove all tag references, pass an empty tag_names array. To remove one or more tags omit them from the tag_names array. If you have the needed permissions, you can only set tags to a specific subset of IMS resources.

POST /v3/tags/set_tags

Request

Custom Headers

X-Ghost
string
Global Search and Tagging reserved.

Possible values: length ≤ 256, Value must match regular expression .*$
x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

account_id
string
The ID of the billing account where the resources to be tagged lives.

Possible values: Value must match regular expression ^[a-fA-F0-9]{32}

Request Body

Required*

SetTagsRequest

List of tag names and resource ID on which the tags should be set. For IMS resources, it is the IMS ID and the IMS data type or keyName.

Examples:

View

Response

Response Body

SetTagsResults

Results of a set_tags request

Status Code

200
The array of set tag operations results.
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
429
Too Many Requests
default
System problem or unexpected error

Example responses

Status 200

{
  "results": [
    {
      "resource_id": "58546459",
      "resource_type": "NETWORK_VLAN_FIREWALL",
      "is_error": false
    }
  ]
}

Get all tags, of any type, that are attached to the resource.

GET /admin/get_all_resource_tags

Request

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

resource_crn
Required*
string
The CRN of the resource

Possible values: Value must match regular expression ^(crn:v1(:[^:]*){8}|[0-9]+)$
offset
integer
The index of the item from which you want to start returning data from.

Possible values: value ≥ 0
Default: 0
limit
integer
The number of tags to return.

Possible values: 1 ≤ value ≤ 1000
Default: 100
tag_type
string
The type of the tag you want to get. Supported values are user, service and access. If not specified, tags of all types are returned.

Allowable values: [user,service,access]

Response

Response Body

getAllResourceTagsResults

A list of tags.

Status Code

200
The list of tags that are attached to the resource.
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token not valid
407
Unsupported operation
429
Too Many Requests
500
Internal server error, IAM not initialized, or malformed IAM credentials
default
System problem or unexpected error

No Sample Response

This method does not specify any sample responses.

Detach all tags, of any type, from the resource.

GET /admin/detach_all_resource_tags

Request

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Query Parameters

resource_crn
Required*
string
The CRN of the resource

Possible values: Value must match regular expression ^(crn:v1(:[^:]*){8}|[0-9]+)$
tag_type
string
The type of the tags you want to detach. Supported values are user, service and access. If not specified, tags of all types are detached.

Allowable values: [user,service,access]

Response

Response Body

DetachAllResourceTagsResults

Results of a detach_all_resource_tags request

Status Code

200
The result of the operation
400
Bad request
401
Unauthorized, wrong authorization token type, or IAM authorization token was not valid.
429
Too Many Requests
default
System problem or unexpected error

Example responses

Status 200

{
  "results": [
    {
      "tot_detached_tags": 10
    }
  ]
}

health endpoint

GET /health

Request

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Response

Response Body

HealthResponse

Definition of success health response

Status Code

200
Success
424
Failed Dependency Error
429
Failed - Too Many Requests

No Sample Response

This method does not specify any sample responses.

alive endpoint

GET /alive

Request

Custom Headers

x-request-id
string
An alphanumeric string that is used to trace the request. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*
x-correlation-id
string
An alphanumeric string that is used to trace the request as a part of a larger context: the same value is used for downstream requests and retries of those requests. The value may include ASCII alphanumerics and any of following segment separators: space ( ), comma (,), hyphen, (-), and underscore (_) and may have a length up to 1024 bytes. The value is considered invalid and must be ignored if that value includes any other character or is longer than 1024 bytes or is fewer than 8 characters. If not specified or invalid, it is automatically replaced by a random (version 4) UUID.

Possible values: Value must match regular expression .*

Response

Response Body

AliveResponse

Definition of success alive response

Status Code

200
Success
429
Too Many Requests
501
Failed Dependency Error

No Sample Response

This method does not specify any sample responses.

Introduction

Types of tags

Filtering tags

Endpoint URLs

Authentication

Auditing

Error handling

Related APIs

Methods

Get all tags

Request

Custom Headers

X-IMS-Auth-Token

x-request-id

x-correlation-id

Query Parameters

account_id

tag_type

full_data

providers

attached_to

offset

limit

timeout

order_by_name

attached_only

parameter

ctx

ListTagsOptions

TransactionID

ImpersonateUser

AccountID

TagType

FullData

Providers

AttachedTo

Offset

Limit

Timeout

OrderByName

AttachedOnly

ListTagsOptions

transactionId

impersonateUser

accountId

tagType

fullData

providers

attachedTo

offset

limit

timeout

orderByName

attachedOnly

parameters

transactionId

impersonateUser

accountId

tagType

fullData

providers

attachedTo

offset

limit

timeout

orderByName

attachedOnly

parameters

transaction_id

impersonate_user

account_id

tag_type

full_data

providers

attached_to

offset

limit

timeout

order_by_name

attached_only