Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add ManagedInstanceDTCs APIs #18770

Merged
merged 16 commits into from
May 24, 2022
Merged

Add ManagedInstanceDTCs APIs #18770

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
7951e14
Added swagger, examples and changed the readme.md file
Apr 21, 2022
ddb7cfd
Fixed spelling errors and examples
Apr 21, 2022
d126152
Added a patch request option and renamed the file to lowercase
Apr 28, 2022
aba361a
Update readme.md
krivi37 Apr 28, 2022
c613fcb
Renamed examples for put and patch update
Apr 29, 2022
8107b87
Merge branch 'dev/skrivokapic/addManagedInstanceDTCsAPIspecs' of http…
Apr 29, 2022
498f99d
Extracted resource properties for patch request
May 11, 2022
6fb2c3f
Added new examples and changed existing ones
May 12, 2022
ebfda31
Added provisioning state to put request
May 17, 2022
2d18c66
Updated put examples
May 17, 2022
1484207
Changed provisioning status in the update examples
May 17, 2022
673a8ac
Updated provisioning state enum
May 18, 2022
4daf240
Removed 202 code from PUT provisioning state response and updated exa…
May 19, 2022
7fbd99d
Removed patch operation and associated examples, also renamed put exa…
May 20, 2022
a893475
Changed descriptions of some models
May 23, 2022
c94a12c
Renamed an example description
May 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion custom-words.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2523,4 +2523,5 @@ Dataworld
Asana
AppFigures
Twilio
getazresiliencystatus
getazresiliencystatus
DTCs
369 changes: 369 additions & 0 deletions ...on/sql/resource-manager/Microsoft.Sql/preview/2022-02-01-preview/ManagedInstanceDtcs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,369 @@
{
"swagger": "2.0",
"info": {
"version": "2022-02-01-preview",
"title": "SqlManagementClient",
"description": "The Azure SQL Database management API provides a RESTful set of web APIs that interact with Azure SQL Database services to manage your databases. The API enables users to create, retrieve, update, and delete databases, servers, and other entities."
},
"host": "management.azure.com",
"schemes": [
"https"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"paths": {
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/managedInstances/{managedInstanceName}/dtc": {
"get": {
"tags": [
"ManagedInstanceDtcs"
],
"description": "Gets a list of the managed instance DTC settings.",
"operationId": "ManagedInstanceDtcs_ListByManagedInstance",
"parameters": [
{
"$ref": "../../../common/v1/types.json#/parameters/ResourceGroupParameter"
},
{
"$ref": "#/parameters/ManagedInstanceNameParameter"
},
{
"$ref": "../../../common/v1/types.json#/parameters/SubscriptionIdParameter"
},
{
"$ref": "../../../common/v1/types.json#/parameters/ApiVersionParameter"
}
],
"responses": {
"200": {
"description": "Successfully retrieved the specified managed instance DTC settings.",
"schema": {
"$ref": "#/definitions/ManagedInstanceDtcListResult"
}
},
"default": {
"description": "*** Error Responses: ***\n\n * 400 ManagementServiceManagedInstanceDtcFeatureDisabled - User tried to interact with Azure SQL Managed Instance DTC settings but DTC feature is currently not supported.\n\n * 400 InvalidDtcVirtualClusterVersion - Virtual cluster version of the Azure SQL Managed Instance \"{0}\" is not supported.\n\n * 404 SubscriptionNotFound - The requested subscription was not found.\n\n * 404 ResourceNotFound - The requested resource was not found."
}
},
"x-ms-pageable": {
"nextLinkName": "nextLink"
},
"x-ms-examples": {
"Gets a list of the managed instance DTC settings.": {
"$ref": "./examples/ManagedInstanceDtcList.json"
}
}
}
},
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/managedInstances/{managedInstanceName}/dtc/{dtcName}": {
"get": {
"tags": [
"ManagedInstanceDtcs"
],
"description": "Gets the managed instance DTC settings.",
"operationId": "ManagedInstanceDtcs_Get",
"parameters": [
{
"$ref": "../../../common/v1/types.json#/parameters/ResourceGroupParameter"
},
{
"$ref": "#/parameters/ManagedInstanceNameParameter"
},
{
"name": "dtcName",
"in": "path",
"description": "The name of the managed instance DTC.",
"required": true,
"type": "string",
"enum": [
"current"
],
"x-ms-enum": {
"name": "DtcName",
"modelAsString": true
}
},
{
"$ref": "../../../common/v1/types.json#/parameters/SubscriptionIdParameter"
},
{
"$ref": "../../../common/v1/types.json#/parameters/ApiVersionParameter"
}
],
"responses": {
"200": {
"description": "Successfully retrieved the specified managed instance DTC settings.",
"schema": {
"$ref": "#/definitions/ManagedInstanceDtc"
}
},
"default": {
"description": "*** Error Responses: ***\n\n * 400 InvalidDtcName - User tried to interact with Azure SQL Managed Instance DTC settings with a DTC name different from 'current'.\n\n * 400 InvalidUpdateDtcOperationParameters - The provided set of parameters in the body of the request is either empty or invalid.\n\n * 400 InvalidDtcAuthenticationMethod - DTC authentication method \"{0}\" is not supported.\n\n * 400 ManagementServiceManagedInstanceDtcFeatureDisabled - User tried to interact with Azure SQL Managed Instance DTC settings but DTC feature is currently not supported.\n\n * 400 InvalidDtcVirtualClusterVersion - Virtual cluster version of the Azure SQL Managed Instance \"{0}\" is not supported.\n\n * 404 SubscriptionNotFound - The requested subscription was not found.\n\n * 404 ResourceNotFound - The requested resource was not found."
}
},
"x-ms-examples": {
"Gets the managed instance DTC settings.": {
"$ref": "./examples/ManagedInstanceDtcGet.json"
}
}
},
"put": {
"tags": [
"ManagedInstanceDtcs"
],
"description": "Updates the managed instance DTC settings.",
"operationId": "ManagedInstanceDtcs_CreateOrUpdate",
"parameters": [
{
"$ref": "../../../common/v1/types.json#/parameters/ResourceGroupParameter"
},
{
"$ref": "#/parameters/ManagedInstanceNameParameter"
},
{
"name": "dtcName",
"in": "path",
"description": "The name of the managed instance DTC.",
"required": true,
"type": "string",
"enum": [
"current"
],
"x-ms-enum": {
"name": "DtcName",
"modelAsString": true
}
},
{
"name": "parameters",
"in": "body",
"description": "Managed instance DTC settings.",
"required": true,
"schema": {
"$ref": "#/definitions/ManagedInstanceDtc"
}
},
{
"$ref": "../../../common/v1/types.json#/parameters/SubscriptionIdParameter"
},
{
"$ref": "../../../common/v1/types.json#/parameters/ApiVersionParameter"
}
],
"responses": {
"200": {
"description": "Successfully updated DTC settings.",
"schema": {
"$ref": "#/definitions/ManagedInstanceDtc"
}
},
"default": {
"description": "*** Error Responses: ***\n\n * 400 InvalidDtcName - User tried to interact with Azure SQL Managed Instance DTC settings with a DTC name different from 'current'.\n\n * 400 InvalidUpdateDtcOperationParameters - The provided set of parameters in the body of the request is either empty or invalid.\n\n * 400 InvalidDtcAuthenticationMethod - DTC authentication method \"{0}\" is not supported.\n\n * 400 ManagementServiceManagedInstanceDtcFeatureDisabled - User tried to interact with Azure SQL Managed Instance DTC settings but DTC feature is currently not supported.\n\n * 400 InvalidDtcVirtualClusterVersion - Virtual cluster version of the Azure SQL Managed Instance \"{0}\" is not supported.\n\n * 404 ResourceNotFound - The requested resource was not found.\n\n * 404 OperationIdNotFound - The operation with Id does not exist.\n\n * 404 OperationIdNotFound - The operation with Id does not exist.\n\n * 409 OperationCancelled - The operation has been cancelled by user.\n\n * 409 OperationInterrupted - The operation on the resource could not be completed because it was interrupted by another operation on the same resource.\n\n * 500 OperationTimedOut - The operation timed out and automatically rolled back. Please retry the operation."
},
"202": {
"description": "Applying DTC settings is in progress"
}
},
"x-ms-long-running-operation": true,
"x-ms-examples": {
"Updates the managed instance DTC settings with all optional parameters specified using PUT request.": {
"$ref": "./examples/ManagedInstanceDtcUpdateMax.json"
},
"Updates the managed instance DTC settings by enabling DTC using PUT request.": {
"$ref": "./examples/ManagedInstanceDtcUpdateEnableDtc.json"
}
}
},
"patch": {
"tags": [
"ManagedInstanceDtcs"
],
"description": "Patches the managed instance DTC settings.",
"operationId": "ManagedInstanceDtcs_Update",
"parameters": [
{
"$ref": "../../../common/v1/types.json#/parameters/ResourceGroupParameter"
},
{
"$ref": "#/parameters/ManagedInstanceNameParameter"
},
{
"name": "dtcName",
"in": "path",
"description": "The name of the managed instance DTC.",
"required": true,
"type": "string",
"enum": [
"current"
],
"x-ms-enum": {
"name": "DtcName",
"modelAsString": true
}
},
{
"name": "parameters",
"in": "body",
"description": "Managed instance DTC settings.",
"required": true,
"schema": {
"$ref": "#/definitions/ManagedInstanceDtc"
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ManagedInstanceDtc

This does not work, since you cannot patch everything in a resource like name and type cannot be patched. Generally teams include a subset of the resource definition with only the properties that can be patched.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The name cannot be changed, it is can only be "current" since this is a singleton object, and it is only used as a route in the request. The only properties that are actually getting updated are the ones in the body of the request. The dtcName is in the URL itself

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ones in the body of the request, meaning the "ManagedInstanceDtcProperties" in this case? Think Suhas is suggesting to create a definition and include those that you'll update.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, but everything which is listed under ManagedInstanceDtc -> ManagedInstanceDtcProperties can be patched. All the properties are mutable except for "dtcHostNameDnsSuffix" which is declared as read only.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall it's just not a good pattern, as user can still pass them, but they are useless. It's a strong recommendation but will not block you on this.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Took a second look on this, if ManagedInstanceDtcProperties is all you needed for patch, why not just pass them?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've passed those

}
},
{
"$ref": "../../../common/v1/types.json#/parameters/SubscriptionIdParameter"
},
{
"$ref": "../../../common/v1/types.json#/parameters/ApiVersionParameter"
}
],
"responses": {
"200": {
"description": "Successfully updated DTC settings.",
"schema": {
"$ref": "#/definitions/ManagedInstanceDtc"
}
},
"default": {
"description": "*** Error Responses: ***\n\n * 400 InvalidDtcName - User tried to interact with Azure SQL Managed Instance DTC settings with a DTC name different from 'current'.\n\n * 400 InvalidUpdateDtcOperationParameters - The provided set of parameters in the body of the request is either empty or invalid.\n\n * 400 InvalidDtcAuthenticationMethod - DTC authentication method \"{0}\" is not supported.\n\n * 400 ManagementServiceManagedInstanceDtcFeatureDisabled - User tried to interact with Azure SQL Managed Instance DTC settings but DTC feature is currently not supported.\n\n * 400 InvalidDtcVirtualClusterVersion - Virtual cluster version of the Azure SQL Managed Instance \"{0}\" is not supported.\n\n * 404 ResourceNotFound - The requested resource was not found.\n\n * 404 OperationIdNotFound - The operation with Id does not exist.\n\n * 404 OperationIdNotFound - The operation with Id does not exist.\n\n * 409 OperationCancelled - The operation has been cancelled by user.\n\n * 409 OperationInterrupted - The operation on the resource could not be completed because it was interrupted by another operation on the same resource.\n\n * 500 OperationTimedOut - The operation timed out and automatically rolled back. Please retry the operation."
},
"202": {
"description": "Applying DTC settings is in progress"
}
Copy link

@zizw123 zizw123 May 4, 2022 •
edited by rkmanda
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are you planning to support both sync and async for 200 and 202? For async patch, the recommend pattern is to use 202 and location header. See: https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/async-api-reference.md#updating-using-patch #Closed

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jamestao

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't swagger document the final Location response which is 200 OK?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We are following https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/async-api-reference.md#202-accepted-and-location-headers
Specifically:
5.If the operation is complete, return the exact same response that would have been returned had the operation been executed synchronously.
Swagger/AutoRest needs some way of determining the structure of the final response, and that is done by providing the sync response format here.

},
"x-ms-long-running-operation": true,
"x-ms-examples": {
"Updates the managed instance DTC settings with all optional parameters specified using PATCH request.": {
"$ref": "./examples/ManagedInstanceDtcUpdateMax.json"
},
"Updates the managed instance DTC settings by enabling DTC using PATCH request.": {
"$ref": "./examples/ManagedInstanceDtcUpdateEnableDtc.json"
}
}
}
}
},
"definitions": {
"ManagedInstanceDtc": {
"description": "SQL Managed Instance DTC",
"type": "object",
"allOf": [
{
"$ref": "../../../common/v1/types.json#/definitions/ProxyResource"
}
],
"properties": {
"properties": {
"$ref": "#/definitions/ManagedInstanceDtcProperties",
"description": "Resource properties.",
"x-ms-client-flatten": true
}
}
},
"ManagedInstanceDtcListResult": {
"description": "A list of managed instance's DTCs.",
"type": "object",
"properties": {
"value": {
"description": "Array of results.",
"type": "array",
"items": {
"$ref": "#/definitions/ManagedInstanceDtc"
},
"readOnly": true
},
"nextLink": {
"description": "Link to retrieve next page of results.",
"type": "string",
"readOnly": true
}
}
},
"ManagedInstanceDtcProperties": {
"description": "The properties of managed instance DTC.",
"type": "object",
"properties": {
"dtcEnabled": {
"description": "Active status of managed instance DTC.",
"type": "boolean"
},
"securitySettings": {
"$ref": "#/definitions/ManagedInstanceDtcSecuritySettings",
"description": "Security settings of managed instance DTC."
},
"externalDnsSuffixSearchList": {
"description": "External dns suffix search list of managed instance DTC.",
"type": "array",
"items": {
"type": "string"
}
},
"dtcHostNameDnsSuffix": {
"description": "Host name dns suffix of managed instance DTC.",
"type": "string",
"readOnly": true
}
}
},
"ManagedInstanceDtcSecuritySettings": {
"description": "The Transaction Manager Communication Settings of the DTC tied to managed instance.",
"type": "object",
"properties": {
"transactionManagerCommunicationSettings": {
"$ref": "#/definitions/ManagedInstanceDtcTransactionManagerCommunicationSettings",
"description": "Transaction Manager communication settings of managed instance DTC."
},
"xaTransactionsEnabled": {
"description": "Allow XA Transactions to managed instance DTC.",
"type": "boolean"
},
"snaLu6point2TransactionsEnabled": {
"description": "Allow SNA LU 6.2 to managed instance DTC.",
"type": "boolean"
}
}
},
"ManagedInstanceDtcTransactionManagerCommunicationSettings": {
"description": "The Transaction Manager Communication Settings of the DTC tied to managed instance.",
"type": "object",
"properties": {
"allowInboundEnabled": {
"description": "Allow Inbound traffic to managed instance DTC.",
"type": "boolean"
},
"allowOutboundEnabled": {
"description": "Allow Outbound traffic of managed instance DTC.",
"type": "boolean"
},
"authentication": {
"description": "Authentication type of managed instance DTC.",
"type": "string"
}
}
}
},
"parameters": {
"ManagedInstanceNameParameter": {
"name": "managedInstanceName",
"in": "path",
"description": "The name of the managed instance.",
"required": true,
"type": "string",
"x-ms-parameter-location": "method"
}
},
"securityDefinitions": {
"azure_auth": {
"type": "oauth2",
"description": "Azure Active Directory OAuth2 Flow",
"flow": "implicit",
"authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
"scopes": {
"user_impersonation": "impersonate your user account"
}
}
}
}
Loading