From 6d4112d65c8d032e4937b4666bbe25d144b55338 Mon Sep 17 00:00:00 2001 From: Hamid Tirmizi Date: Wed, 29 Jan 2020 16:56:24 -0800 Subject: [PATCH 1/6] Descriptive changes for the tags API --- .../stable/2019-10-01/resources.json | 117 ++++++++++-------- 1 file changed, 66 insertions(+), 51 deletions(-) diff --git a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json index f55e67b508e2..9b0b38de05e8 100644 --- a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json +++ b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json @@ -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", @@ -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.", @@ -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", @@ -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" } @@ -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", @@ -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" } @@ -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", @@ -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.", @@ -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 returns a summary of tag usage under the given subscription, including the predefined.", "parameters": [ { "$ref": "#/parameters/ApiVersionParameter" @@ -4009,8 +4012,9 @@ "tags": [ "Tags" ], - "operationId": "Tags_ResourceCreate", - "description": "Create or Replace existing tags with passing in tags.", + "operationId": "Tags_CreateOrReplaceTagsOnObject", + "summary": "Creates or replaces the entire set of tags on an object.", + "description": "This operation allows adding or replacing the entire set of tags on the specified object. The object can be a resource or a subscription. An object can have a maximum of 50 tags.", "parameters": [ { "$ref": "#/parameters/ScopeParameter" @@ -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" } @@ -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" } } @@ -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_PatchTagsOnObject", + "summary": "Selectively updates the set of tags on an object.", + "description": "This operation allows replacing, merging or selectively deleting tags on the specified object. The object can be a resource or a subscription. An object 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" @@ -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" } @@ -4093,8 +4096,9 @@ "tags": [ "Tags" ], - "operationId": "Tags_ResourceGet", - "description": "Gets all the tags for the resource.", + "operationId": "Tags_GetTagsOnObject", + "summary": "Gets the entire set of tags on an object.", + "description": "This operation allows retrieving all tags on the specified object. The object can be a resource or a subscription.", "parameters": [ { "$ref": "#/parameters/ScopeParameter" @@ -4105,7 +4109,7 @@ ], "responses": { "200": { - "description": "OK - Returns tag information about the resource.", + "description": "Returns tags from the specified object.", "schema": { "$ref": "#/definitions/TagsResource" } @@ -4118,10 +4122,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" } } @@ -4130,8 +4134,9 @@ "tags": [ "Tags" ], - "operationId": "Tags_ResourceDelete", - "description": "Deletes all the tags for the resource.", + "operationId": "Tags_DeleteTagsOnObject", + "summary": "Deletes the entire set of tags on an object.", + "description": "This operation allows deleting all tags on the specified object. The object can be a resource or a subscription.", "parameters": [ { "$ref": "#/parameters/ScopeParameter" @@ -4142,7 +4147,7 @@ ], "responses": { "200": { - "description": "OK" + "description": "Tags successfully deleted." }, "default": { "description": "Error response describing why the operation failed.", @@ -5028,7 +5033,7 @@ "id": { "readOnly": true, "type": "string", - "description": "The tag ID." + "description": "The tag value ID." }, "tagValue": { "type": "string", @@ -5047,7 +5052,7 @@ "id": { "readOnly": true, "type": "string", - "description": "The tag ID." + "description": "The tag name ID." }, "tagName": { "type": "string", @@ -5498,7 +5503,7 @@ } }, "Tags": { - "description": "key and value pairs for tags", + "description": "A dictionary of name and value pairs.", "properties": { "tags": { "type": "object", @@ -5509,13 +5514,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", @@ -5524,27 +5529,37 @@ }, "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" - } - ] + } } }, "parameters": { From 71aa8f8ba4c6da1f5e50b3945894b41f20dd2432 Mon Sep 17 00:00:00 2001 From: Hamid Tirmizi Date: Wed, 29 Jan 2020 17:28:52 -0800 Subject: [PATCH 2/6] Remove templateHash, fix ARM header in response --- ...PutDeploymentWithOnErrorDeploymentSpecificDeployment.json | 2 -- .../Microsoft.Resources/stable/2019-10-01/resources.json | 5 +++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentSpecificDeployment.json b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentSpecificDeployment.json index 9140493abad3..c30e3d7da7cf 100644 --- a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentSpecificDeployment.json +++ b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentSpecificDeployment.json @@ -29,7 +29,6 @@ "uri": "{templateUri}", "contentVersion": "1.0.0.0" }, - "templateHash": "9132645722898483367", "parameters": {}, "mode": "Complete", "provisioningState": "Accepted", @@ -103,7 +102,6 @@ "uri": "{templateUri}", "contentVersion": "1.0.0.0" }, - "templateHash": "9132645722898483367", "parameters": {}, "mode": "Complete", "provisioningState": "Accepted", diff --git a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json index 9b0b38de05e8..ba94aac9163a 100644 --- a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json +++ b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json @@ -4058,7 +4058,7 @@ "tags": [ "Tags" ], - "operationId": "Tags_PatchTagsOnObject", + "operationId": "Tags_UpdateTagsOnObject", "summary": "Selectively updates the set of tags on an object.", "description": "This operation allows replacing, merging or selectively deleting tags on the specified object. The object can be a resource or a subscription. An object 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": [ @@ -5559,7 +5559,8 @@ "$ref": "#/definitions/Tags", "description": "The set of tags." } - } + }, + "x-ms-azure-resource": true } }, "parameters": { From d046a642fa6cf04360ca59a1e2dc559ea280aae5 Mon Sep 17 00:00:00 2001 From: Hamid Tirmizi Date: Thu, 30 Jan 2020 11:09:35 -0800 Subject: [PATCH 3/6] Another instance of templateHash removed --- .../PutDeploymentWithOnErrorDeploymentLastSuccessful.json | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentLastSuccessful.json b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentLastSuccessful.json index 6974c8d72105..f75a4ff7641b 100644 --- a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentLastSuccessful.json +++ b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/examples/PutDeploymentWithOnErrorDeploymentLastSuccessful.json @@ -28,7 +28,6 @@ "uri": "{templateUri}", "contentVersion": "1.0.0.0" }, - "templateHash": "9132645722898483367", "parameters": {}, "mode": "Complete", "provisioningState": "Accepted", @@ -102,7 +101,6 @@ "uri": "{templateUri}", "contentVersion": "1.0.0.0" }, - "templateHash": "9132645722898483367", "parameters": {}, "mode": "Complete", "provisioningState": "Accepted", From 0c8b362640edbab3c1cc8d750b0bc07f271c22eb Mon Sep 17 00:00:00 2001 From: Hamid Tirmizi Date: Thu, 30 Jan 2020 13:58:04 -0800 Subject: [PATCH 4/6] List doc fixed --- .../Microsoft.Resources/stable/2019-10-01/resources.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json index ba94aac9163a..7adf007f0a52 100644 --- a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json +++ b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json @@ -3493,7 +3493,7 @@ ], "operationId": "Tags_List", "summary": "Gets a summary of tag usage under the subscription.", - "description": "This operation returns a summary of tag usage under the given subscription, including the predefined.", + "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" From 4b435c84bed15416827acf4f607e3db01d758d70 Mon Sep 17 00:00:00 2001 From: Hamid Tirmizi Date: Fri, 31 Jan 2020 12:37:17 -0800 Subject: [PATCH 5/6] Replace to Update on PUT --- .../Microsoft.Resources/stable/2019-10-01/resources.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json index 7adf007f0a52..3e2272a3922b 100644 --- a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json +++ b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json @@ -4012,8 +4012,8 @@ "tags": [ "Tags" ], - "operationId": "Tags_CreateOrReplaceTagsOnObject", - "summary": "Creates or replaces the entire set of tags on an object.", + "operationId": "Tags_CreateOrUpdateTagsOnObject", + "summary": "Creates or updates the entire set of tags on an object.", "description": "This operation allows adding or replacing the entire set of tags on the specified object. The object can be a resource or a subscription. An object can have a maximum of 50 tags.", "parameters": [ { From 80acc5f2cb8de766eabe46b1a83bc9985b22fb7c Mon Sep 17 00:00:00 2001 From: Hamid Tirmizi Date: Fri, 31 Jan 2020 15:20:57 -0800 Subject: [PATCH 6/6] Fixed TagsOnObject to AtScope --- .../stable/2019-10-01/resources.json | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json index 3e2272a3922b..1a52af27dd7f 100644 --- a/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json +++ b/specification/resources/resource-manager/Microsoft.Resources/stable/2019-10-01/resources.json @@ -4012,9 +4012,9 @@ "tags": [ "Tags" ], - "operationId": "Tags_CreateOrUpdateTagsOnObject", - "summary": "Creates or updates the entire set of tags on an object.", - "description": "This operation allows adding or replacing the entire set of tags on the specified object. The object can be a resource or a subscription. An object can have a maximum of 50 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" @@ -4058,9 +4058,9 @@ "tags": [ "Tags" ], - "operationId": "Tags_UpdateTagsOnObject", - "summary": "Selectively updates the set of tags on an object.", - "description": "This operation allows replacing, merging or selectively deleting tags on the specified object. The object can be a resource or a subscription. An object 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.", + "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" @@ -4096,9 +4096,8 @@ "tags": [ "Tags" ], - "operationId": "Tags_GetTagsOnObject", - "summary": "Gets the entire set of tags on an object.", - "description": "This operation allows retrieving all tags on the specified object. The object can be a resource or a subscription.", + "operationId": "Tags_GetAtScope", + "summary": "Gets the entire set of tags on a resource or subscription.", "parameters": [ { "$ref": "#/parameters/ScopeParameter" @@ -4134,9 +4133,8 @@ "tags": [ "Tags" ], - "operationId": "Tags_DeleteTagsOnObject", - "summary": "Deletes the entire set of tags on an object.", - "description": "This operation allows deleting all tags on the specified object. The object can be a resource or a subscription.", + "operationId": "Tags_DeleteAtScope", + "summary": "Deletes the entire set of tags on a resource or subscription.", "parameters": [ { "$ref": "#/parameters/ScopeParameter"