{ "openapi": "3.0.0", "info": { "contact": { "email": "michele.crudele@it.ibm.com", "name": "IBM" }, "description": "## Introduction\n\nYou 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. \n\nTags 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. \n\nSDKs 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](https://github.com/IBM/ibm-cloud-sdk-common) on GitHub.\n\nInstalling the Java SDK\n\nMaven\n\n```xml\n\n\tcom.ibm.cloud\n\tglobal-tagging\n\t{version}\n\n```\n\nGradle\n\n```bash\ncompile 'com.ibm.cloud:global-tagging:{version}'\n```\n\nReplace `{version}` in these examples with the release version.\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-java-sdk](https://github.com/IBM/platform-services-java-sdk)\n\nInstalling the Node SDK\n\n```bash\nnpm install @ibm-cloud/platform-services\n```\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-node-sdk](https://github.com/IBM/platform-services-node-sdk)\n\nInstalling the Python SDK\n\n```bash\npip install --upgrade \"ibm-platform-services\"\n```\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-python-sdk](https://github.com/IBM/platform-services-python-sdk)\n\nInstalling the Go SDK\n\nGo modules (recommended): Add the following import in your code, and then run `go build` or `go mod tidy`\n\n```go\nimport (\n\t\"github.com/IBM/platform-services-go-sdk/globaltaggingv1\"\n)\n```\n\nGo get\n\n```bash\ngo get -u github.com/IBM/platform-services-go-sdk/globaltaggingv1\n```\n\nView on GitHub\n\n[https://github.com/IBM/platform-services-go-sdk](https://github.com/IBM/platform-services-go-sdk)\n\n### Types of tags\n\nThe Tagging API supports three types of tag: `service`, `user`, and `access`. \n\n- 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. \n\n 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.\n\n- 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.\n\n 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.\n\n- 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. \n\n 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).\n\n### Filtering tags\n\nGlobal Search and Tagging stores the different type of tags attached to a resource within a different attribute of the resource document: \n\n- Service tags are stored within `service_tags` attribute. \n- User tags are stored within the `tags` attribute. \n- Access management tags are stored within the `access_tags` attribute. \n\nSo, you can add filters to those attributes when [searching for resources](https://cloud.ibm.com/apidocs/search). \n\nFor example, the following filter matches all resources tagged with the *your_service:your_tag* service tag. \n\n```\nservice_tags:\"your_service:your_tag\"\n```\n\nThe following filter matches all resources that are tagged with any service tag starting with *your_service:*. \n```\nservice_tags:your_service:*\n```\n\nThe following filter matches all resources that are tagged with the *my_tag* user tag. \n\n```\ntags: \"my_tag\"\n```\n\nFinally, the following filter matches all resources that are tagged with the *env:public* access management tag.\n\n```\naccess_tags: \"env:public\"\n```\n\n## Endpoint URLs\n\nThe 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.\n\n```\nhttps://tags.global-search-tagging.cloud.ibm.com\n```\n\nIf 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](https://cloud.ibm.com/docs/account?topic=account-vrf-service-endpoint).\n\n- Private endpoint URL for VPC infrastructure (Dallas, Washington, Sydney, London, Frankfurt, Madrid, San Paulo, Tokyo, Osaka, Toronto, Montreal, Chennai, Mumbai regions): `https://tags.private.global-search-tagging.cloud.ibm.com`\n- Private endpoint URL for classic infrastructure:\n - Dallas `https://tags.private.us-south.global-search-tagging.cloud.ibm.com`\n - Washington `https://tags.private.us-east.global-search-tagging.cloud.ibm.com`\n - Sydney `https://tags.private.au-syd.global-search-tagging.cloud.ibm.com`\n - London `https://tags.private.eu-gb.global-search-tagging.cloud.ibm.com`\n - Frankfurt `https://tags.private.eu-de.global-search-tagging.cloud.ibm.com`\n\nExample API request\n\n```\ncurl -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}\" } ] }'\n```\n\nReplace `{IAM token}`, `{tagName}` and `{resourceCRN}` in this example with the values for your particular API call.\n\n## Authentication\n\nAuthorization 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. \n\nObtaining an IAM token for an authenticated user or service ID is described in the [IAM Identity Services API](https://cloud.ibm.com/apidocs/iam-identity-token-api) documentation. \n\nTo use the API, add a valid IAM token to the HTTP Authorization request header, for example, `--header \"Authorization: Bearer \"`.\n\nWhen 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:\n- Programmatically by constructing an IAM authenticator instance and supplying your IAM API key \n- 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\n\nIn 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.\n\nFor more information, see the Authentication section of the [IBM Cloud SDK Common](https://github.com/IBM/ibm-cloud-sdk-common/blob/main/README.md) documentation.\n\nTo 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](https://cloud.ibm.com/docs/account?topic=account-account-services).\n\nTo retrieve your access token:\n\n```bash\ncurl -X POST \\\n \"https://iam.cloud.ibm.com/identity/token\" \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --header 'Accept: application/json' \\\n --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' \\\n --data-urlencode 'apikey='\n```\n\nReplace `` with your IAM API key.\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport GLOBAL_TAGGING_URL=\nexport GLOBAL_TAGGING_AUTHTYPE=iam\nexport GLOBAL_TAGGING_APIKEY=\n```\n\nExample of constructing the service client\n```go\nimport {\n \"github.com/IBM/platform-services-go-sdk/globaltaggingv1\"\n}\n...\nserviceClientOptions := &globaltaggingv1.GlobalTaggingV1Options{}\nserviceClient, err := globaltaggingv1.NewGlobalTaggingV1UsingExternalConfig(serviceClientOptions)\n```\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport GLOBAL_TAGGING_URL=\nexport GLOBAL_TAGGING_AUTHTYPE=iam\nexport GLOBAL_TAGGING_APIKEY=\n```\n\nExample of constructing the service client\n```java\nimport com.ibm.cloud.platform_services.global_tagging.v1.GlobalTagging;\n...\nGlobalTagging serviceClient = GlobalTagging.newInstance();\n```\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport GLOBAL_TAGGING_URL=\nexport GLOBAL_TAGGING_AUTHTYPE=iam\nexport GLOBAL_TAGGING_APIKEY=\n```\n\nExample of constructing the service client\n```javascript\nconst GlobalTaggingV1 = require('@ibm-cloud/platform-services/global-tagging/v1');\n...\nconst serviceClient = GlobalTaggingV1.newInstance({});\n```\n\nSetting client options through external configuration\n\nExample environment variables, where `` is the endpoint URL and `` is your IAM API key\n```sh\nexport GLOBAL_TAGGING_URL=\nexport GLOBAL_TAGGING_AUTHTYPE=iam\nexport GLOBAL_TAGGING_APIKEY=\n```\n\nExample of constructing the service client\n```python\nfrom ibm_platform_services import GlobalTaggingV1\n...\nglobal_tagging_service = GlobalTaggingV1.new_instance()\n```\n\n## Auditing\n\nYou 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.\n\nFor more information about how to track tagging activity, see [Auditing events for account management](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-at_events_acc_mgt).\n\n## Error handling\n\nThe 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.\n\n| HTTP error code | Description | Recovery |\n|-----------------|-------------|----------|\n| `200` | Success | The request was successful. |\n| `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. |\n| `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.\t|\n| `404` | Not Found | The requested resource could not be found. |\n| `409` | Conflict | The entity is already in the requested state. |\n| `410` | Gone | The resource is valid but has been removed already in a previous call |\n| `500` | Internal Server Error | *offering_name* is currently unavailable. Your request could not be processed. Wait a few minutes and try again. |\n\n## Related APIs\n\nAfter 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](https://cloud.ibm.com/apidocs/search).", "license": { "name": "This product includes software originally developed by IBM Corporation, Copyright 2018-2020 IBM Corp.", "url": "https://www.ibm.com/legal/us/en/copytrade.shtml" }, "title": "Global Tagging", "version": "1.2.0", "x-alternate-name": "global_tagging", "x-ibm-name": "tagging-api-specification", "x-codegen-config": { "java": { "apiPackage": "com.ibm.cloud.platform_services" }, "go": { "apiPackage": "github.com/IBM/platform-services-go-sdk", "improvedNameFormattingV2": true }, "python": { "apiPackage": "ibm_platform_services" } }, "x-sdk-supported-languages": [ "curl", "go", "java", "node", "python" ], "x-github": "https://github.ibm.com/cloud-api-docs/tagging", "x-github-issues": "https://github.ibm.com/cloud-api-docs/tagging/issues/new", "x-last-updated": "2023-05-09" }, "servers": [ { "url": "https://tags.global-search-tagging.cloud.ibm.com" } ], "paths": { "/v3/tags": { "get": { "x-swagger-router-controller": "swagger_controllers", "operationId": "list_tags", "x-eov-operation-id": "list_tags", "x-eov-operation-handler": "api/swagger_controllers", "security": [ { "IAM": [] } ], "tags": [ "Tags" ], "summary": "Get all tags", "description": "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.\n", "parameters": [ { "in": "header", "name": "X-IMS-Auth-Token", "x-sdk-exclude": true, "deprecated": true, "description": "The infrastructure authentication token, which can be used for searching the infrastructure tags. It is deprecated in favor of IAM authentication token.\n", "schema": { "type": "string", "pattern": "^Basic .*$" } }, { "$ref": "#/components/parameters/x-request-id" }, { "$ref": "#/components/parameters/x-correlation-id" }, { "in": "query", "name": "account_id", "description": "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`.\n", "required": false, "allowReserved": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" } }, { "in": "query", "name": "tag_type", "required": false, "description": "The type of the tag you want to list. Supported values are `user`, `service` and `access`.\n", "schema": { "type": "string", "enum": [ "user", "service", "access" ], "default": "user" } }, { "in": "query", "name": "full_data", "description": "If set to `true`, this query returns the provider, `ghost`, `ims` or `ghost,ims`, where the tag exists and the number of attached resources.\n", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "providers", "required": false, "description": "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.\n", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ghost", "ims" ] }, "default": [ "ghost" ] } }, { "in": "query", "name": "attached_to", "description": "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`).\n", "required": false, "allowReserved": true, "schema": { "type": "string", "pattern": "^(crn:v1(:[^:]*){7}:.*|[a-zA-Z0-9_\\-\\.]+)$" } }, { "in": "query", "name": "offset", "description": "The offset is the index of the item from which you want to start returning data from.\n", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "in": "query", "name": "limit", "description": "The number of tags to return.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "in": "query", "name": "timeout", "description": "The timeout in milliseconds, bounds the request to run within the specified time value. It returns the accumulated results until time runs out.\n", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 600000, "default": 0 } }, { "in": "query", "name": "order_by_name", "required": false, "description": "Order the output by tag name.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "in": "query", "name": "attached_only", "required": false, "description": "Filter on attached tags. If `true`, it returns only tags that are attached to one or more resources. If `false`, it returns all tags.\n", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "A result paging with the list of tags that match the provided filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagList" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "401": { "description": "Unauthorized, wrong authorization token type, or IAM authorization token not valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "407": { "description": "Unsupported operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "500": { "description": "Internal server error, IAM not initialized, or malformed IAM credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "default": { "description": "System problem or unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X GET --header \"Authorization: Bearer {iam_token}\" \\\n", " --header \"Accept: application/json\" \\\n", " \"{base_url}/v3/tags?tag_type=user&attached_only=true&full_data=true&providers=ghost&offset=0&limit=10&order_by_name=asc\"" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "listTagsOptions := globalTaggingService.NewListTagsOptions()\n", "listTagsOptions.SetTagType(\"user\")\n", "listTagsOptions.SetAttachedOnly(true)\n", "listTagsOptions.SetFullData(true)\n", "listTagsOptions.SetProviders([]string{\"ghost\"})\n", "listTagsOptions.SetOrderByName(\"asc\")\n", "\n", "tagList, response, err := globalTaggingService.ListTags(listTagsOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(tagList, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "ListTagsOptions listTagsOptions = new ListTagsOptions.Builder()\n", " .tagType(\"user\")\n", " .attachedOnly(true)\n", " .fullData(true)\n", " .addProviders(\"ghost\")\n", " .orderByName(\"asc\")\n", " .build();\n", "\n", "Response response = service.listTags(listTagsOptions).execute();\n", "TagList tagList = response.getResult();\n", "System.out.println(tagList.toString());" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " tagType: 'user',\n", " attachedOnly: true,\n", " fullData: true,\n", " providers: ['ghost'],\n", " orderByName: 'asc',\n", "};\n", "\n", "globalTaggingService.listTags(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "tag_list = global_tagging_service.list_tags(\n", " tag_type='user',\n", " attached_only=True,\n", " full_data=True,\n", " providers=['ghost'],\n", " order_by_name='asc').get_result()\n", "\n", "print(json.dumps(tag_list, indent=2))" ] } ] } ] } } }, "post": { "x-swagger-router-controller": "swagger_controllers", "operationId": "create_tag", "x-eov-operation-id": "create_tag", "x-eov-operation-handler": "api/swagger_controllers", "security": [ { "IAM": [] } ], "tags": [ "Tags" ], "summary": "Create an access management tag", "description": "Create an access management tag. To create an `access` tag, you must have the access listed in the [Granting users access to tag resources](https://cloud.ibm.com/docs/account?topic=account-access) documentation. `service` and `user` tags cannot be created upfront. They are created when they are attached for the first time to a resource.\n", "x-ibm-permissions": { "description": "This action applies only to access management tags.", "actions": [ { "name": "ghost-tags.create-access-tag" } ] }, "x-ibm-events": { "events": [ { "name": "global-search-tagging.tag.create" } ] }, "parameters": [ { "$ref": "#/components/parameters/x-request-id" }, { "$ref": "#/components/parameters/x-correlation-id" }, { "in": "query", "name": "account_id", "description": "The ID of the billing account where the tag must be created.\n", "required": false, "allowReserved": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" } }, { "in": "query", "name": "tag_type", "required": false, "description": "The type of the tags you want to create. The only allowed value is `access`.\n", "schema": { "type": "string", "enum": [ "access" ], "default": "access" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagBody" } } }, "description": "An array of access management tags to be created.", "required": true }, "responses": { "200": { "description": "The tag was created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagResults" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "401": { "description": "Unauthorized, wrong authorization token type, or IAM authorization token was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "System problem or unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST --header \"Authorization: Bearer {iam_token}\" \\\n", " --header \"Accept: application/json\" \\\n", " --header \"Content-Type: application/json\" \\\n", " -d '{ \"tag_names\": [\"env:example-access-tag\"] }' \\\n", " \"{base_url}/v3/tags?tag_type=access\"" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "createTagOptions := globalTaggingService.NewCreateTagOptions(\n", " []string{\"env:example-access-tag\"},\n", ")\n", "createTagOptions.SetTagType(\"access\")\n", "\n", "createTagResults, response, err := globalTaggingService.CreateTag(createTagOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(createTagResults, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "CreateTagOptions createTagOptions = new CreateTagOptions.Builder()\n", " .addTagNames(\"env:example-access-tag\")\n", " .tagType(\"access\")\n", " .build();\n", "\n", "Response response = service.createTag(createTagOptions).execute();\n", "CreateTagResults createTagResults = response.getResult();\n", "System.out.println(createTagResults);" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " tagNames: ['env:example-access-tag'],\n", " tagType: 'access',\n", "};\n", "\n", "globalTaggingService.createTag(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "create_tag_results = global_tagging_service.create_tag(\n", " tag_names=['env:example-access-tag'],\n", " tag_type='access').get_result()\n", "\n", "print(json.dumps(create_tag_results, indent=2))" ] } ] } ] } } }, "delete": { "x-swagger-router-controller": "swagger_controllers", "operationId": "delete_tag_all", "x-eov-operation-id": "delete_tag_all", "x-eov-operation-handler": "api/swagger_controllers", "security": [ { "IAM": [] } ], "tags": [ "Tags" ], "summary": "Delete all unused tags", "description": "Delete the tags that are not attached to any resource.\n", "x-ibm-permissions": { "description": "This action applies only to access management tags.", "actions": [ { "name": "ghost-tags.delete-access-tag" } ] }, "x-ibm-events": { "events": [ { "name": "global-search-tagging.tags.delete" } ] }, "parameters": [ { "in": "header", "name": "X-IMS-Auth-Token", "x-sdk-exclude": true, "deprecated": true, "description": "The infrastructure authentication token, which can be used for for deleting the infrastructure tags. It is deprecated in favor of IAM authentication token.\n", "required": false, "schema": { "type": "string", "pattern": "^Basic .*$" } }, { "$ref": "#/components/parameters/x-request-id" }, { "$ref": "#/components/parameters/x-correlation-id" }, { "in": "query", "name": "providers", "required": false, "description": "Select a provider. Supported values are `ghost` and `ims`.", "schema": { "type": "string", "enum": [ "ghost", "ims" ], "default": "ghost" } }, { "in": "query", "name": "account_id", "description": "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`.\n", "required": false, "allowReserved": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" } }, { "in": "query", "name": "tag_type", "required": false, "description": "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`).\n", "schema": { "type": "string", "enum": [ "user", "service", "access" ], "default": "user" } } ], "responses": { "200": { "description": "A results page that includes the list of tags that have been deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTagsResult" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "401": { "description": "Unauthorized, wrong authorization token type, or IAM authorization token was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "System problem or unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X DELETE --header \"Authorization: Bearer {iam_token}\" \\\n", " --header \"Accept: application/json\" \\\n", " \"{base_url}/v3/tags?tag_type=user\"" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "deleteTagAllOptions := globalTaggingService.NewDeleteTagAllOptions()\n", "deleteTagAllOptions.SetTagType(\"user\")\n", "\n", "deleteTagsResult, response, err := globalTaggingService.DeleteTagAll(deleteTagAllOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(deleteTagsResult, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "DeleteTagAllOptions deleteTagAllOptions = new DeleteTagAllOptions.Builder()\n", " .tagType(\"user\")\n", " .build();\n", "\n", "Response response = service.deleteTagAll(deleteTagAllOptions).execute();\n", "DeleteTagsResult deleteTagsResult = response.getResult();\n", "\n", "System.out.println(deleteTagsResult.toString());" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " tagType: 'access',\n", "};\n", "\n", "globalTaggingService.deleteTagAll(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "delete_tags_result = global_tagging_service.delete_tag_all(\n", " tag_type='user').get_result()\n", "\n", "print(json.dumps(delete_tags_result, indent=2))" ] } ] } ] } } } }, "/v3/tags/{tag_name}": { "delete": { "x-swagger-router-controller": "swagger_controllers", "operationId": "delete_tag", "x-eov-operation-id": "delete_tag", "x-eov-operation-handler": "api/swagger_controllers", "security": [ { "IAM": [] } ], "tags": [ "Tags" ], "summary": "Delete an unused tag", "description": "Delete an existing tag. A tag can be deleted only if it is not attached to any resource.\n", "x-ibm-permissions": { "description": "This action applies only to access management tags.", "actions": [ { "name": "ghost-tags.delete-access-tag" } ] }, "x-ibm-events": { "events": [ { "name": "global-search-tagging.tag.delete" } ] }, "parameters": [ { "in": "path", "name": "tag_name", "description": "The name of tag to be deleted.", "required": true, "allowReserved": true, "schema": { "type": "string", "maxLength": 128, "pattern": "^[\\s]*[A-Za-z0-9:_.\\-][A-Za-z0-9\\s:_.\\-]*$" } }, { "in": "header", "name": "X-IMS-Auth-Token", "x-sdk-exclude": true, "deprecated": true, "description": "The infrastructure authentication token, which can be used for for deleting an infrastructure tag. It is deprecated in favor of IAM authentication token.\n", "required": false, "schema": { "type": "string", "pattern": "^Basic .*$" } }, { "$ref": "#/components/parameters/x-request-id" }, { "$ref": "#/components/parameters/x-correlation-id" }, { "in": "query", "name": "providers", "required": false, "description": "Select a provider. Supported values are `ghost` and `ims`. To delete tags both in Global Search and Tagging and in IMS, use `ghost,ims`", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ghost", "ims" ] }, "default": [ "ghost" ] } }, { "in": "query", "name": "account_id", "description": "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.\n", "required": false, "allowReserved": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" } }, { "in": "query", "name": "tag_type", "required": false, "description": "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`).\n", "schema": { "type": "string", "enum": [ "user", "service", "access" ], "default": "user" } } ], "responses": { "200": { "description": "Success message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteTagResults" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "401": { "description": "Unauthorized, wrong authorization token type, or IAM authorization token was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "System problem or unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ " curl -X DELETE --header \"Authorization: Bearer {iam_token}\" \\\n", "--header \"Accept: application/json\" \\\n", "\"{base_url}/v3/tags/{tag_name}?tag_type=access\"" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "deleteTagOptions := globalTaggingService.NewDeleteTagOptions(\"env:example-access-tag\")\n", "deleteTagOptions.SetTagType(\"access\")\n", "\n", "deleteTagResults, response, err := globalTaggingService.DeleteTag(deleteTagOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(deleteTagResults, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "DeleteTagOptions deleteTagOptions = new DeleteTagOptions.Builder()\n", " .tagName(\"env:example-access-tag\")\n", " .tagType(\"access\")\n", " .build();\n", "\n", "Response response = service.deleteTag(deleteTagOptions).execute();\n", "DeleteTagResults deleteTagResults = response.getResult();\n", "System.out.println(deleteTagResults.toString());" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const params = {\n", " tagName: 'env:example-access-tag',\n", " tagType: 'access',\n", "};\n", "\n", "globalTaggingService.deleteTag(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "delete_tag_results = global_tagging_service.delete_tag(\n", " tag_name='env:example-access-tag',\n", " tag_type='access').get_result()\n", "\n", "print(json.dumps(delete_tag_results, indent=2))" ] } ] } ] } } } }, "/v3/tags/attach": { "post": { "x-swagger-router-controller": "swagger_controllers", "operationId": "attach_tag", "x-eov-operation-id": "attach_tag", "x-eov-operation-handler": "api/swagger_controllers", "security": [ { "IAM": [] } ], "tags": [ "Tags" ], "summary": "Attach tags", "description": "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).\n", "x-ibm-permissions": { "description": "This action applies only to user tags. Because service tags are managed by IBM services. IAM actions do not apply to them.\n\nTo attach a `user` tag on a resource, you must have the access listed in the [Granting users access to tag resources](https://cloud.ibm.com/docs/account?topic=account-access) documentation.\n\nTo 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.\n\nTo attach an `access` tag, you must be the resource administrator within the account. You can attach only `access` tags that already exist.\n\nIn 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.\n\nIn 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.", "actions": [ { "name": "global-search-tagging.tag.attach-user-tag" }, { "name": "global-search-tagging.tag.attach-access-tag" }, { "name": "global-search-tagging.tag.detach-user-tag" }, { "name": "global-search-tagging.tag.detach-access-tag" } ] }, "x-ibm-events": { "events": [ { "name": ".tag.attach" } ] }, "parameters": [ { "in": "header", "name": "X-IMS-Auth-Token", "x-sdk-exclude": true, "deprecated": true, "description": "The infrastructure authentication token, which can be used for attaching an infrastructure tag. It is deprecated in favor of IAM authentication token.\n", "required": false, "schema": { "type": "string", "pattern": "^Basic .*$" } }, { "in": "header", "name": "creator-iam-id", "x-sdk-exclude": true, "description": "The user on whose behalf the attach operation must be performed (_for administrators only_).\n", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_,-]*$" } }, { "in": "header", "name": "created-at", "x-sdk-exclude": true, "description": "The time when the tag creation must be recorded (_for administrators only_).\n", "required": false, "schema": { "type": "string", "pattern": "\\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" } }, { "$ref": "#/components/parameters/x-request-id" }, { "$ref": "#/components/parameters/x-correlation-id" }, { "in": "query", "name": "account_id", "description": "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.\n", "required": false, "allowReserved": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" } }, { "in": "query", "name": "tag_type", "required": false, "description": "The type of the tag. Supported values are `user`, `service` and `access`. `service` and `access` are not supported for IMS resources.\n", "schema": { "type": "string", "enum": [ "user", "service", "access" ], "default": "user" } }, { "in": "query", "name": "replace", "required": false, "description": "Flag to request replacement of all attached tags. Set `true` if you want to replace all tags attached to the resource with the current ones. Default value is false.\n", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "update", "required": false, "description": "Flag to request update of attached tags in the format `key:value`. Here's how it works for each tag in the request body: If the tag to attach is in the format `key:value`, the System will atomically detach all existing tags starting with `key:` and attach the new `key:value` tag. If no such tags exist, a new `key:value` tag will be attached. If the tag is not in the `key:value` format (e.g., a simple label), the System will attach the label as usual. The update query parameter is available for user and access management tags, but not for service tags.\n", "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachTagRequest" } } }, "description": "Array of tag names and list of resource IDs on which the tags should be attached or a valid Global Search string that dynamically identifies the resources to attach tags to. In that case the query cannot resolve to more than 100 resources, otherwise the entire operation will fail. The caller must have the permission to manage tags on those resources. The operation will fail for the other resources and a specific error is returned in the operation response. 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.\n", "required": true }, "responses": { "200": { "description": "The array of tag attach operations result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagResults" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "401": { "description": "Unauthorized, wrong authorization token type, or IAM authorization token was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "System problem or unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ " curl -X POST --header \"Authorization: Bearer {iam_token}\" \\\n", "--header \"Accept: application/json\" \\\n", "--header \"Content-Type: application/json\" \\\n", "-d '{ \"resources\": [{ \"resource_id\": \"{RESOURCE_CRN}\" }], \"tag_names\": [\"tag_test_1\", \"tag_test_2\"] }' \\\n", "\"{base_url}/v3/tags/attach?tag_type=user\"" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "resourceModel := &globaltaggingv1.Resource{\n", " ResourceID: &resourceCRN,\n", "}\n", "\n", "attachTagOptions := globalTaggingService.NewAttachTagOptions(\n", " []globaltaggingv1.Resource{*resourceModel},\n", ")\n", "attachTagOptions.SetTagNames([]string{\"tag_test_1\", \"tag_test_2\"})\n", "attachTagOptions.SetTagType(\"user\")\n", "\n", "tagResults, response, err := globalTaggingService.AttachTag(attachTagOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(tagResults, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "Resource resourceModel = new Resource.Builder().resourceId(resourceCRN).build();\n", "AttachTagOptions attachTagOptions = new AttachTagOptions.Builder()\n", " .addResources(resourceModel)\n", " .addTagNames(\"tag_test_1\")\n", " .addTagNames(\"tag_test_2\")\n", " .build();\n", "\n", "Response response = service.attachTag(attachTagOptions).execute();\n", "TagResults tagResults = response.getResult();\n", "System.out.println(tagResults.toString());" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const resourceModel = {\n", " resource_id: resourceCrn,\n", "};\n", "\n", "const params = {\n", " resources: [resourceModel],\n", " tagNames: [\"tag_test_1\", \"tag_test_2\"],\n", " tagType: 'user',\n", "};\n", "\n", "globalTaggingService.attachTag(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "resource_model = {'resource_id': resource_crn}\n", "\n", "tag_results = global_tagging_service.attach_tag(\n", " resources=[resource_model],\n", " tag_names=['tag_test_1', 'tag_test_2'],\n", " tag_type='user').get_result()\n", "\n", "print(json.dumps(tag_results, indent=2))" ] } ] } ] } } } }, "/v3/tags/detach": { "post": { "x-swagger-router-controller": "swagger_controllers", "operationId": "detach_tag", "x-eov-operation-id": "detach_tag", "x-eov-operation-handler": "api/swagger_controllers", "security": [ { "IAM": [] } ], "tags": [ "Tags" ], "summary": "Detach tags", "description": "Detaches one or more tags from one or more resources.\n", "x-ibm-permissions": { "description": "This action applies only to user tags. Because service tags are managed by IBM services, IAM actions do not apply to them.\n\nTo detach a `user` tag on a resource you must have the permissions listed in the\n[Granting users access to tag resources](https://cloud.ibm.com/docs/account?topic=account-access)\ndocumentation.\n\nTo detach a `service` tag, you must be an authorized Service. If that is the case, then you\ncan detach a `service` tag with your registered `prefix` from any resource in any account. The\naccount ID must be set through the `account_id` query parameter.\n\nTo detach an `access` tag, you must be the resource administrator within the account.", "actions": [ { "name": "global-search-tagging.tag.detach-user-tag" }, { "name": "global-search-tagging.tag.detach-access-tag" } ] }, "x-ibm-events": { "events": [ { "name": ".tag.detach" } ] }, "parameters": [ { "in": "header", "name": "X-IMS-Auth-Token", "x-sdk-exclude": true, "deprecated": true, "description": "The infrastructure authentication token, which can be used for detaching an infrastructure tag. It is deprecated in favor of IAM authentication token.\n", "required": false, "schema": { "type": "string", "pattern": "^Basic .*$" } }, { "$ref": "#/components/parameters/x-request-id" }, { "$ref": "#/components/parameters/x-correlation-id" }, { "in": "query", "name": "account_id", "description": "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.\n", "required": false, "allowReserved": true, "schema": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" } }, { "in": "query", "name": "tag_type", "required": false, "description": "The type of the tag. Supported values are `user`, `service` and `access`. `service` and `access` are not supported for IMS resources.\n", "schema": { "type": "string", "enum": [ "user", "service", "access" ], "default": "user" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetachTagRequest" } } }, "description": "Array of tag names and the list of resources to detach tags from, or a valid Global Search string that dynamically identifies the resources to detach tags from. In that case the query cannot resolve to more than 100 resources, otherwise the entire operation will fail. The caller must have the permission to manage tags on those resources. The operation will fail for the other resources and a specific error is returned in the operation response.\n", "required": true }, "responses": { "200": { "description": "The array of tag detach operations results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagResults" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "401": { "description": "Unauthorized, wrong authorization token type, or IAM authorization token was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" } } } }, "default": { "description": "System problem or unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Errors" } } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "curl -X POST --header \"Authorization: Bearer {iam_token}\" \\\n", " --header \"Accept: application/json\" \\\n", " --header \"Content-Type: application/json\" \\\n", " -d '{ \"resources\": [{ \"resource_id\": \"{RESOURCE_CRN}\" }], \"tag_names\": [\"tag_test_1\", \"tag_test_2\"] }' \\\n", " \"{base_url}/v3/tags/detach?tag_type=user\"" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "resourceModel := &globaltaggingv1.Resource{\n", " ResourceID: &resourceCRN,\n", "}\n", "\n", "detachTagOptions := globalTaggingService.NewDetachTagOptions(\n", " []globaltaggingv1.Resource{*resourceModel},\n", ")\n", "detachTagOptions.SetTagNames([]string{\"tag_test_1\", \"tag_test_2\"})\n", "detachTagOptions.SetTagType(\"user\")\n", "\n", "tagResults, response, err := globalTaggingService.DetachTag(detachTagOptions)\n", "if err != nil {\n", " panic(err)\n", "}\n", "b, _ := json.MarshalIndent(tagResults, \"\", \" \")\n", "fmt.Println(string(b))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "Resource resourceModel = new Resource.Builder().resourceId(resourceCRN).build();\n", "DetachTagOptions detachTagOptions = new DetachTagOptions.Builder()\n", " .addResources(resourceModel)\n", " .addTagNames(\"tag_test_1\")\n", " .addTagNames(\"tag_test_2\")\n", " .tagType(\"user\")\n", " .build();\n", "\n", "Response response = service.detachTag(detachTagOptions).execute();\n", "TagResults tagResults = response.getResult();\n", "System.out.println(tagResults.toString());" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "const resourceModel = {\n", " resource_id: resourceCrn,\n", "};\n", "\n", "const params = {\n", " resources: [resourceModel],\n", " tagNames: [\"tag_test_1\", \"tag_test_2\"],\n", " tagType: 'user',\n", "};\n", "\n", "globalTaggingService.detachTag(params)\n", " .then(res => {\n", " console.log(JSON.stringify(res.result, null, 2));\n", " })\n", " .catch(err => {\n", " console.warn(err)\n", " });" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "source": [ "resource_model = {'resource_id': resource_crn}\n", "\n", "tag_results = global_tagging_service.detach_tag(\n", " resources=[resource_model],\n", " tag_names=['tag_test_1', 'tag_test_2'],\n", " tag_type='user').get_result()\n", "\n", "print(json.dumps(tag_results, indent=2))" ] } ] } ] } } } } }, "components": { "parameters": { "x-request-id": { "in": "header", "name": "x-request-id", "description": "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.", "required": false, "schema": { "type": "string", "pattern": ".*" } }, "x-correlation-id": { "in": "header", "name": "x-correlation-id", "description": "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.", "required": false, "schema": { "type": "string", "pattern": ".*" } } }, "securitySchemes": { "IAM": { "type": "apiKey", "description": "A valid IAM token. Remember to add the `bearer` prefix to the token.", "name": "Authorization", "in": "header" } }, "schemas": { "RateLimitError": { "description": "Error encountered when hitting rate limiter.", "type": "string" }, "Error": { "description": "Error encountered in processing in the request.", "type": "object", "properties": { "code": { "description": "A code that identifies the error.", "type": "string" }, "response": { "description": "The response received for the request.", "type": "string" }, "message": { "description": "A description of the error detected in the request.", "type": "string" }, "level": { "description": "The severity level of the error.", "type": "string", "enum": [ "error", "warning", "info" ] }, "description": { "description": "A description of the solution to the error.", "type": "string" }, "more_info": { "description": "The location of additional information about the error.", "type": "string" } }, "required": [ "code", "response", "message", "level" ] }, "Errors": { "description": "Error response", "type": "object", "properties": { "errors": { "description": "Detailed errors list", "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "QueryString": { "description": "A valid Global Search string.", "type": "object", "additionalProperties": false, "properties": { "query_string": { "type": "string", "minLength": 1, "description": "The Lucene-formatted query string" } }, "required": [ "query_string" ], "example": { "query_string": "region:(us-south OR us-east) AND service_name:cloudantsqldb" } }, "ResourceList": { "description": "List of resources on which the tagging operation operates on", "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Resource" } }, "AttachTagRequest": { "description": "A list of resources to attach tags to, or a valid Global Search string that dynamically identifies the resources to attach tags to. In that case the query cannot resolve to more than 100 resources, otherwise the entire operation will fail. The caller must have the permission to manage tags on those resources. The operation will fail for the other resources and a specific error is returned in the operation response.\n", "type": "object", "additionalProperties": false, "properties": { "tag_name": { "description": "The name of the tag to attach", "type": "string", "maxLength": 128, "pattern": "^[ ]*[A-Za-z0-9:_.\\-][A-Za-z0-9 :_.\\-]*$" }, "tag_names": { "description": "An array of tag names to attach", "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "maxLength": 128, "pattern": "^[ ]*[A-Za-z0-9:_.\\-][A-Za-z0-9 :_.\\-]*$" } }, "resources": { "$ref": "#/components/schemas/ResourceList" }, "query": { "$ref": "#/components/schemas/QueryString" } }, "not": { "anyOf": [ { "required": [ "tag_name", "tag_names" ], "type": "object" }, { "required": [ "resources", "query" ], "type": "object" } ] }, "minProperties": 2, "maxProperties": 2, "example": { "tag_names": [ "tag_test_1", "tag_test_2" ], "resources": [ { "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1b061f4485b34360a8f8ee049080dc13" }, { "resource_id": "58546459", "resource_type": "SoftLayer_Virtual_Guest" } ] } }, "DetachTagRequest": { "description": "A list of resources to detach tags from, or a valid Global Search string that dynamically identifies the resources to detach tags from. In that case the query cannot resolve to more than 100 resources, otherwise the entire operation will fail. The caller must have the permission to manage tags on those resources. The operation will fail for the other resources and a specific error is returned in the operation response.\n", "type": "object", "additionalProperties": false, "properties": { "tag_name": { "description": "The name of the tag to detach", "type": "string", "maxLength": 128, "pattern": "^([A-Za-z0-9:_ .\\-]+|\\*|[A-Za-z0-9_ .\\-]+:\\*)$" }, "tag_names": { "description": "An array of tag names to detach", "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "maxLength": 128, "pattern": "^([A-Za-z0-9:_ .\\-]+|\\*|[A-Za-z0-9_ .\\-]+:\\*)$" } }, "resources": { "$ref": "#/components/schemas/ResourceList" }, "query": { "$ref": "#/components/schemas/QueryString" } }, "not": { "anyOf": [ { "required": [ "tag_name", "tag_names" ], "type": "object" }, { "required": [ "resources", "query" ], "type": "object" } ] }, "minProperties": 2, "maxProperties": 2, "example": { "tag_names": [ "tag_test_1", "tag_test_2" ], "resources": [ { "resource_id": "crn:v1:staging:public:resource-controller::a/5c2ac0d93c69e82c6c9c7c78dc4beda3::resource-group:1b061f4485b34360a8f8ee049080dc13" }, { "resource_id": "75546457", "resource_type": "SoftLayer_Hardware" } ] } }, "SetTagsRequest": { "description": "Array of tag names and resource ID on which the tags are set.", "type": "object", "properties": { "tag_names": { "description": "An array of tag names to set", "type": "array", "minItems": 0, "items": { "type": "string", "maxLength": 128, "pattern": "^[\\s]*[A-Za-z0-9:_.\\-][A-Za-z0-9\\s:_.\\-]*$" } }, "resources": { "description": "List of resources on which the tags are set. Current implementation support only one resource whose type is included in a specific subset of IMS resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/Resource" } } }, "required": [ "tag_names", "resources" ], "example": { "tag_names": [ "tag_test_1", "tag_test_2" ], "resources": [ { "resource_id": "12546459", "resource_type": "NETWORK_VLAN_FIREWALL" } ] } }, "RestoreTagsRequest": { "description": "Array of crns.", "type": "object", "properties": { "resources": { "description": "An array of resources to restore tags to", "type": "array", "minItems": 0, "maxItems": 100, "items": { "type": "string", "maxLength": 1024, "pattern": "^(crn:v1(:[^:]*){7}:.*)$" } } }, "required": [ "resources" ], "example": { "resources": [ "crn:v1:staging:public:is:us-south:a/c21088ea7a014ffb8f6a7bc4304699a0::image:r134-e19563c8-2d9c-464b-bd72-974af0b3d6b5" ] } }, "Resource": { "description": "A resource that might have tags that are attached.", "properties": { "resource_id": { "description": "The CRN or IMS ID of the resource", "type": "string", "maxLength": 1024, "pattern": "^(crn:v1(:[^:]*){7}:.*|[a-zA-Z0-9_\\-\\.]+)$" }, "resource_type": { "description": "The IMS resource type of the resource. It can be one of SoftLayer_Virtual_DedicatedHost, SoftLayer_Hardware, SoftLayer_Hardware_Server, SoftLayer_Network_Application_Delivery_Controller, SoftLayer_Network_Vlan, SoftLayer_Network_Vlan_Firewall, SoftLayer_Network_Component_Firewall, SoftLayer_Network_Firewall_Module_Context, SoftLayer_Virtual_Guest", "type": "string", "pattern": "^[A-Za-z0-9_ :.-]*$" } }, "required": [ "resource_id" ] }, "TagList": { "description": "A list of tags.", "type": "object", "properties": { "total_count": { "type": "integer", "minimum": 0, "description": "Set the occurrences of the total tags that are associated with this account." }, "offset": { "description": "The offset at which tags are returned", "type": "integer", "minimum": 0 }, "limit": { "description": "The number of tags requested to be returned", "type": "integer", "minimum": 1 }, "items": { "description": "Array of output results.", "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } }, "Tag": { "description": "A tag", "properties": { "name": { "type": "string", "description": "The name of the tag." } }, "required": [ "name" ] }, "TagResults": { "description": "Results of an attach_tag or detach_tag request", "type": "object", "properties": { "results": { "description": "Array of results of an attach_tag or detach_tag request.", "type": "array", "items": { "$ref": "#/components/schemas/TagResultsItem" } } }, "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" } ] } }, "TagResultsItem": { "description": "Result of an attach_tag or detach_tag request for a tagged resource", "properties": { "resource_id": { "description": "The CRN or IMS ID of the resource", "type": "string" }, "is_error": { "type": "boolean", "description": "It is `true` if the operation exits with an error." }, "message": { "type": "string", "description": "Error message returned when the operation fails" } }, "required": [ "resource_id" ], "example": [ { "provider": "ims", "resource_id": "12345676", "resource_type": "SoftLayer_Virtual_Guest", "is_error": true, "response": "IMS_API_ERROR", "message": "Error calling IMS REST API endpoint", "code": "GST915E", "level": "error", "httpCode": 500, "description": "SoftLayer_Exception_Public", "more_info": "No tag found with the name \"string\"", "subCode": 500 } ] }, "DeleteTagResults": { "description": "Results of a delete_tag request.", "type": "object", "properties": { "results": { "description": "Array of results of a delete_tag request.", "type": "array", "items": { "$ref": "#/components/schemas/DeleteTagResultsItem" } } } }, "DeleteTagResultsItem": { "description": "Result of a delete_tag request.", "properties": { "provider": { "description": "The provider of the tag.", "type": "string", "enum": [ "ghost", "ims" ] }, "is_error": { "type": "boolean", "description": "It is `true` if the operation exits with an error (for example, the tag does not exist)." } }, "additionalProperties": true }, "DeleteTagsResult": { "description": "Results of deleting unattatched tags.", "type": "object", "properties": { "total_count": { "description": "The number of tags that have been deleted.", "type": "integer" }, "errors": { "description": "It is set to true if there is at least one tag operation in error.", "type": "boolean" }, "items": { "description": "The list of tag operation results.", "type": "array", "items": { "$ref": "#/components/schemas/DeleteTagsResultItem" } } } }, "DeleteTagsResultItem": { "description": "Result of a delete_tags request.", "properties": { "tag_name": { "type": "string", "description": "The name of the deleted tag." }, "is_error": { "type": "boolean", "description": "true if the tag was not deleted." } } }, "SetTagsResults": { "x-sdk-exclude": true, "description": "Results of a set_tags request", "type": "object", "properties": { "results": { "description": "Array of results of an set_tags request.", "type": "array", "items": { "$ref": "#/components/schemas/TagResultsItem" } } }, "example": { "results": [ { "resource_id": "58546459", "resource_type": "NETWORK_VLAN_FIREWALL", "is_error": false } ] } }, "CreateTagBody": { "description": "list of tag names to be created.", "type": "object", "required": [ "tag_names" ], "properties": { "tag_names": { "description": "An array of tag names to create", "type": "array", "minItems": 1, "maxItems": 100, "items": { "description": "The name of the tag to create. Note that access tags must be in the form key:value", "type": "string", "maxLength": 128, "pattern": "^[ ]*[A-Za-z0-9:_.\\-][A-Za-z0-9 :_.\\-]*$" } } } }, "CreateTagResults": { "description": "Results of a create tag(s) request.", "properties": { "results": { "description": "Array of results of a create_tag request.", "type": "array", "items": { "type": "object", "properties": { "tag_name": { "description": "The name of the tag created", "type": "string" }, "is_error": { "description": "true if the tag was not created (for example, the tag already exists).", "type": "boolean" } } } } } }, "getAllResourceTagsResults": { "description": "A list of tags.", "type": "array", "items": { "type": "object", "properties": { "name": { "description": "The name of the tag.", "type": "string" }, "type": { "description": "The type of the tag.", "type": "string" } } } }, "DetachAllResourceTagsResults": { "description": "Results of a detach_all_resource_tags request", "type": "object", "properties": { "tot_detached_tags": { "description": "The total number of detached tags", "type": "number" } }, "example": { "results": [ { "tot_detached_tags": 10 } ] } }, "RestoreTagsResults": { "description": "Results of a restore_tags request.", "type": "object", "properties": { "results": { "description": "results array", "type": "array", "items": { "$ref": "#/components/schemas/RestoreTagsResultsItem" } } } }, "RestoreTagsResultsItem": { "description": "Item of the restore_tags results.", "type": "object", "properties": { "resource_id": { "description": "resource_id.", "type": "string" }, "tags": { "description": "list of user tags restored.", "type": "array", "items": { "type": "string" } }, "service_tags": { "description": "list of service tags restored.", "type": "array", "items": { "type": "string" } }, "access_tags": { "description": "list of access tags restored.", "type": "array", "items": { "type": "string" } } } }, "HealthSummary": { "description": "Information about of microservice health.", "type": "object", "additionalProperties": true, "properties": { "plan": { "description": "plan service", "type": "string" }, "status": { "description": "status service", "type": "string" }, "depStatus": { "description": "status dependencies service", "type": "string" }, "serviceInput": { "description": "service input", "type": "string" }, "responseTime": { "description": "response Time", "type": "integer" }, "deployVersion": { "description": "deploy version", "type": "string" }, "depCloudantTagDb": { "description": "Cloudant cluster dependencies status", "type": "integer" }, "serviceOutput": { "description": "service output", "type": "string" }, "depIstioEgress": { "description": "Istio cluster dependencies status", "type": "integer" }, "depMaintenance": { "description": "Maintenance status", "type": "integer" }, "depIamXacml": { "description": "IAM dependency status", "type": "integer" }, "depUserMgmt": { "description": "User management dependency status", "type": "integer" } } }, "HealthResponse": { "description": "Definition of success health response", "type": "object", "additionalProperties": true, "properties": { "service": { "description": "Name of the microservice", "type": "string" }, "version": { "description": "Version of the microservice", "type": "string" }, "health": { "description": "Information about of microservice health", "type": "array", "items": { "$ref": "#/components/schemas/HealthSummary" } }, "region": { "description": "Information about kubernetes cluster", "type": "string" }, "timestamp": { "description": "Current timestamp", "type": "string" } } }, "AliveResponse": { "description": "Definition of success alive response", "type": "object", "additionalProperties": true, "properties": { "deployVersion": { "description": "deploy version", "type": "string" }, "httpCode": { "description": "code http", "type": "integer" } } }, "AliveResponseError": { "description": "Definition of failed alive response", "type": "object", "additionalProperties": true, "properties": { "message": { "description": "message text", "type": "string" }, "stack": { "description": "error stack", "type": "string" } } } } } }