Skip to content

Commit

Permalink
Updating the descriptions of newly added tags API related operations …
Browse files Browse the repository at this point in the history 
…for better docs (#8258)

* Descriptive changes for the tags API

* Remove templateHash, fix ARM header in response

* Another instance of templateHash removed

* List doc fixed

* Replace to Update on PUT

* Fixed TagsOnObject to AtScope
  • Loading branch information
@hamidtirmizi
hamidtirmizi authored Feb 4, 2020
1 parent b91c2b9 commit 2474c56
Show file tree
Hide file tree
Showing 3 changed files with 64 additions and 54 deletions.
2 changes: 0 additions & 2 deletions ...esources/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentLastSuccessful.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@
"uri": "{templateUri}",
"contentVersion": "1.0.0.0"
},
"templateHash": "9132645722898483367",
"parameters": {},
"mode": "Complete",
"provisioningState": "Accepted",
Expand Down Expand Up @@ -102,7 +101,6 @@
"uri": "{templateUri}",
"contentVersion": "1.0.0.0"
},
"templateHash": "9132645722898483367",
"parameters": {},
"mode": "Complete",
"provisioningState": "Accepted",
Expand Down
2 changes: 0 additions & 2 deletions ...rces/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentSpecificDeployment.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@
"uri": "{templateUri}",
"contentVersion": "1.0.0.0"
},
"templateHash": "9132645722898483367",
"parameters": {},
"mode": "Complete",
"provisioningState": "Accepted",
Expand Down Expand Up @@ -103,7 +102,6 @@
"uri": "{templateUri}",
"contentVersion": "1.0.0.0"
},
"templateHash": "9132645722898483367",
"parameters": {},
"mode": "Complete",
"provisioningState": "Accepted",
Expand Down
114 changes: 64 additions & 50 deletions ...ification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3314,7 +3314,8 @@
"Tags"
],
"operationId": "Tags_DeleteValue",
"description": "Deletes a tag value.",
"summary": "Deletes a predefined tag value for a predefined tag name.",
"description": "This operation allows deleting a value from the list of predefined values for an existing predefined tag name. The value being deleted must not be in use as a tag value for the given tag name for any resource.",
"parameters": [
{
"name": "tagName",
Expand All @@ -3339,10 +3340,10 @@
],
"responses": {
"200": {
"description": "OK"
"description": "Predefined tag value successfully deleted."
},
"204": {
"description": "No Content"
"description": "Predefined tag value did not exist."
},
"default": {
"description": "Error response describing why the operation failed.",
Expand All @@ -3357,7 +3358,8 @@
"Tags"
],
"operationId": "Tags_CreateOrUpdateValue",
"description": "Creates a tag value. The name of the tag must already exist.",
"summary": "Creates a predefined value for a predefined tag name.",
"description": "This operation allows adding a value to the list of predefined values for an existing predefined tag name. A tag value can have a maximum of 256 characters.",
"parameters": [
{
"name": "tagName",
Expand All @@ -3382,13 +3384,13 @@
],
"responses": {
"200": {
"description": "OK - Returns information about the tag value.",
"description": "Predefined tag value already exists. Returns information about the predefined tag value.",
"schema": {
"$ref": "#/definitions/TagValue"
}
},
"201": {
"description": "Created - Returns information about the tag value.",
"description": "Predefined tag value successfully created. Returns information about the predefined tag value.",
"schema": {
"$ref": "#/definitions/TagValue"
}
Expand All @@ -3408,8 +3410,8 @@
"Tags"
],
"operationId": "Tags_CreateOrUpdate",
"summary": "Creates a tag in the subscription.",
"description": "The tag name can have a maximum of 512 characters and is case insensitive. Tag names created by Azure have prefixes of microsoft, azure, or windows. You cannot create tags with one of these prefixes.",
"summary": "Creates a predefined tag name.",
"description": "This operation allows adding a name to the list of predefined tag names for the given subscription. A tag name can have a maximum of 512 characters and is case-insensitive. Tag names cannot have the following prefixes which are reserved for Azure use: 'microsoft', 'azure', 'windows'.",
"parameters": [
{
"name": "tagName",
Expand All @@ -3427,13 +3429,13 @@
],
"responses": {
"200": {
"description": "OK - Returns information about the tag.",
"description": "Predefined tag name already exists. Returns information about the predefined tag name.",
"schema": {
"$ref": "#/definitions/TagDetails"
}
},
"201": {
"description": "Created - Returns information about the tag.",
"description": "Predefined tag name successfully created. Returns information about the predefined tag name.",
"schema": {
"$ref": "#/definitions/TagDetails"
}
Expand All @@ -3451,8 +3453,8 @@
"Tags"
],
"operationId": "Tags_Delete",
"summary": "Deletes a tag from the subscription.",
"description": "You must remove all values from a resource tag before you can delete it.",
"summary": "Deletes a predefined tag name.",
"description": "This operation allows deleting a name from the list of predefined tag names for the given subscription. The name being deleted must not be in use as a tag name for any resource. All predefined values for the given name must have already been deleted.",
"parameters": [
{
"name": "tagName",
Expand All @@ -3470,10 +3472,10 @@
],
"responses": {
"200": {
"description": "OK"
"description": "Predefined tag name successfully deleted."
},
"204": {
"description": "No Content"
"description": "Predefined tag name did not exist."
},
"default": {
"description": "Error response describing why the operation failed.",
Expand All @@ -3490,7 +3492,8 @@
"Tags"
],
"operationId": "Tags_List",
"description": "Gets the names and values of all resource tags that are defined in a subscription.",
"summary": "Gets a summary of tag usage under the subscription.",
"description": "This operation performs a union of predefined tags, resource tags, resource group tags and subscription tags, and returns a summary of usage for each tag name and value under the given subscription. In case of a large number of tags, this operation may return a previously cached result.",
"parameters": [
{
"$ref": "#/parameters/ApiVersionParameter"
Expand Down Expand Up @@ -4009,8 +4012,9 @@
"tags": [
"Tags"
],
"operationId": "Tags_ResourceCreate",
"description": "Create or Replace existing tags with passing in tags.",
"operationId": "Tags_CreateOrUpdateAtScope",
"summary": "Creates or updates the entire set of tags on a resource or subscription.",
"description": "This operation allows adding or replacing the entire set of tags on the specified resource or subscription. The specified entity can have a maximum of 50 tags.",
"parameters": [
{
"$ref": "#/parameters/ScopeParameter"
Expand All @@ -4024,13 +4028,12 @@
"required": true,
"schema": {
"$ref": "#/definitions/TagsResource"
},
"description": "Parameters for creating multiple tags."
}
}
],
"responses": {
"200": {
"description": "OK - Returns added tag information about the resource.",
"description": "Tags updated successfully. Returns tags from the specified object.",
"schema": {
"$ref": "#/definitions/TagsResource"
}
Expand All @@ -4043,10 +4046,10 @@
}
},
"x-ms-examples": {
"Creates multiple tags for a tracked resource.": {
"Update tags on a resource": {
"$ref": "./examples/PutTagsResource.json"
},
"Create multiple tags for a subscription.": {
"Update tags on a subscription": {
"$ref": "./examples/PutTagsSubscription.json"
}
}
Expand All @@ -4055,8 +4058,9 @@
"tags": [
"Tags"
],
"operationId": "Tags_ResourceUpdate",
"description": "Update multiple tags: if the tagKey exists, update tagValue with the new value; if not, insert the new record.",
"operationId": "Tags_UpdateAtScope",
"summary": "Selectively updates the set of tags on a resource or subscription.",
"description": "This operation allows replacing, merging or selectively deleting tags on the specified resource or subscription. The specified entity can have a maximum of 50 tags at the end of the operation. The 'replace' option replaces the entire set of existing tags with a new set. The 'merge' option allows adding tags with new names and updating the values of tags with existing names. The 'delete' option allows selectively deleting tags based on given names or name/value pairs.",
"parameters": [
{
"$ref": "#/parameters/ScopeParameter"
Expand All @@ -4069,14 +4073,13 @@
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/TagPatchRequest"
},
"description": "Parameters for updating multiple tags."
"$ref": "#/definitions/TagsPatchResource"
}
}
],
"responses": {
"200": {
"description": "OK - Returns updated tag information about the resource.",
"description": "Tags updated successfully. Returns tags from the specified object.",
"schema": {
"$ref": "#/definitions/TagsResource"
}
Expand All @@ -4093,8 +4096,8 @@
"tags": [
"Tags"
],
"operationId": "Tags_ResourceGet",
"description": "Gets all the tags for the resource.",
"operationId": "Tags_GetAtScope",
"summary": "Gets the entire set of tags on a resource or subscription.",
"parameters": [
{
"$ref": "#/parameters/ScopeParameter"
Expand All @@ -4105,7 +4108,7 @@
],
"responses": {
"200": {
"description": "OK - Returns tag information about the resource.",
"description": "Returns tags from the specified object.",
"schema": {
"$ref": "#/definitions/TagsResource"
}
Expand All @@ -4118,10 +4121,10 @@
}
},
"x-ms-examples": {
"Gets all the tags for a tracked resource.": {
"Get tags on a resource": {
"$ref": "./examples/GetTagsResource.json"
},
"Gets all the tags for a subscription.": {
"Get tags on a subscription": {
"$ref": "./examples/GetTagsSubscription.json"
}
}
Expand All @@ -4130,8 +4133,8 @@
"tags": [
"Tags"
],
"operationId": "Tags_ResourceDelete",
"description": "Deletes all the tags for the resource.",
"operationId": "Tags_DeleteAtScope",
"summary": "Deletes the entire set of tags on a resource or subscription.",
"parameters": [
{
"$ref": "#/parameters/ScopeParameter"
Expand All @@ -4142,7 +4145,7 @@
],
"responses": {
"200": {
"description": "OK"
"description": "Tags successfully deleted."
},
"default": {
"description": "Error response describing why the operation failed.",
Expand Down Expand Up @@ -5028,7 +5031,7 @@
"id": {
"readOnly": true,
"type": "string",
"description": "The tag ID."
"description": "The tag value ID."
},
"tagValue": {
"type": "string",
Expand All @@ -5047,7 +5050,7 @@
"id": {
"readOnly": true,
"type": "string",
"description": "The tag ID."
"description": "The tag name ID."
},
"tagName": {
"type": "string",
Expand Down Expand Up @@ -5498,7 +5501,7 @@
}
},
"Tags": {
"description": "key and value pairs for tags",
"description": "A dictionary of name and value pairs.",
"properties": {
"tags": {
"type": "object",
Expand All @@ -5509,13 +5512,13 @@
}
}
},
"TagPatchRequest": {
"TagsPatchResource": {
"type": "object",
"description": "Tag Request for Patch operation.",
"description": "Wrapper resource for tags patch API request only.",
"properties": {
"operation": {
"type": "string",
"description": "The operation type for the patch api.",
"description": "The operation type for the patch API.",
"enum": [
"Replace",
"Merge",
Expand All @@ -5524,27 +5527,38 @@
},
"properties": {
"$ref": "#/definitions/Tags",
"description": "tags object passing in the request."
"description": "The set of tags."
}
}
},
"TagsResource": {
"type": "object",
"description": "Tags for the resource.",
"description": "Wrapper resource for tags API requests and responses.",
"required": [
"properties"
],
"properties": {
"id": {
"readOnly": true,
"type": "string",
"description": "The ID of the tags wrapper resource."
},
"name": {
"readOnly": true,
"type": "string",
"description": "The name of the tags wrapper resource."
},
"type": {
"readOnly": true,
"type": "string",
"description": "The type of the tags wrapper resource."
},
"properties": {
"$ref": "#/definitions/Tags",
"description": "tags property."
"description": "The set of tags."
}
},
"allOf": [
{
"$ref": "../../../../../common-types/resource-management/v1/types.json#/definitions/Resource"
}
]
"x-ms-azure-resource": true
}
},
"parameters": {
Expand Down

0 comments on commit 2474c56

Please sign in to comment.