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 2 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
305 changes: 305 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,305 @@
{
"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"
},
{
"name": "managedInstanceName",
"in": "path",
"description": "The name of the managed instance.",
"required": true,
"type": "string"
},
{
"$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"
},
{
"name": "managedInstanceName",
"in": "path",
"description": "The name of the managed instance.",
"required": true,
"type": "string"
},
{
"name": "dtcName",
"in": "path",
"description": "Name of the DTC instance used.",
"required": true,
"type": "string",
"enum": [
"current"
],
"x-ms-enum": {
"name": "DtcName",
krivi37 marked this conversation as resolved.
Show resolved Hide resolved
"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 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"
},
{
"name": "managedInstanceName",
"in": "path",
"description": "The name of the managed instance.",
"required": true,
"type": "string"
},
{
"name": "dtcName",
"in": "path",
"description": "Name of the DTC instance used.",
"required": true,
"type": "string",
"enum": [
"current"
],
"x-ms-enum": {
"name": "DtcName",
"modelAsString": true
}
},
{
"name": "parameters",
"in": "body",
"description": "Settings of the DTC tied to the Managed instance.",
"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 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.": {
"$ref": "./examples/ManagedInstanceDtcUpdateMax.json"
},
"Updates the managed instance DTC settings by enabling DTC.": {
"$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"
},
krivi37 marked this conversation as resolved.
Show resolved Hide resolved
"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"
Copy link

Choose a reason for hiding this comment

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

consider updating these boolean values to enum as explained here :

https://armwiki.azurewebsites.net/rp_onboarding/process/api_review_best_practices.html

"Replace boolean/switch properties with better enum"

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Is this really needed? These values should only have True and False as values, and from what I see on the linked post:
"Even if you still believe [True, False] are the correct values for a property, you should use a string enum with values [True, False] instead of boolean. Enums are always a more flexible and future proof option because they allow additional values to be added in the future in a non-breaking way, e.g. [True, False, Unknown]."

These values are optional, so not setting them is not a problem (in other words, we don't need the "Unknown" option). Also, since they just determine whether some DTC options are enabled, they can only be "true" or "false". They also cannot be aggregated into a single property since they deal with logically different things.

Copy link

Choose a reason for hiding this comment

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

its not mandatory , but in general is a good rule of thumb. Often we see as a service grows , modelling things as boolean puts you in a corner when the scenario scope expands and you end up needing to have another bool to model something else. In your case it could be something like maybe 3 months down the line you need to have a new state like "allowInboundFromAzureStorage" (hypothetical , I do not know the specifics of your service) and then that ends up becoming another bool rather than an enum which is what it should be. I will not block sgn off on this comment , but would still would urge you to consider fixing this.

},
"authentication": {
"description": "Authentication type of managed instance DTC.",
"type": "string"
}
}
}
},
"parameters": {},
"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"
}
}
}
}
35 changes: 35 additions & 0 deletions ...urce-manager/Microsoft.Sql/preview/2022-02-01-preview/examples/ManagedInstanceDtcGet.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
{
"parameters": {
"subscriptionId": "00000000-1111-2222-3333-444444444444",
"resourceGroupName": "testrg",
"managedInstanceName": "testinstance",
"dtcName": "current",
"api-version": "2022-02-01-preview"
},
"responses": {
"200": {
"body": {
"properties": {
"dtcEnabled": true,
"securitySettings": {
"transactionManagerCommunicationSettings": {
"allowInboundEnabled": false,
"allowOutboundEnabled": true,
"authentication": "NoAuth"
},
"xaTransactionsEnabled": false,
"snaLu6point2TransactionsEnabled": false
},
"externalDnsSuffixSearchList": [
"dns.example1.com",
"dns.example2.com"
],
"dtcHostNameDnsSuffix": "dtcHostNameSuffixExample.com"
},
"id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Sql/managedInstances/testinstance/dtc/current",
"name": "current",
"type": "Microsoft.Sql/managedInstances/dtc"
}
}
}
}
38 changes: 38 additions & 0 deletions ...rce-manager/Microsoft.Sql/preview/2022-02-01-preview/examples/ManagedInstanceDtcList.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
{
"parameters": {
"subscriptionId": "00000000-1111-2222-3333-444444444444",
"resourceGroupName": "testrg",
"managedInstanceName": "testinstance",
"api-version": "2022-02-01-preview"
},
"responses": {
"200": {
"body": {
"value": [
{
"properties": {
"dtcEnabled": true,
"securitySettings": {
"transactionManagerCommunicationSettings": {
"allowInboundEnabled": false,
"allowOutboundEnabled": true,
"authentication": "NoAuth"
},
"xaTransactionsEnabled": false,
"snaLu6point2TransactionsEnabled": false
},
"externalDnsSuffixSearchList": [
"dns.example1.com",
"dns.example2.com"
],
"dtcHostNameDnsSuffix": "dtcHostNameSuffixExample.com"
},
"id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/testrg/providers/Microsoft.Sql/managedInstances/testinstance/dtc/current",
"name": "current",
"type": "Microsoft.Sql/managedInstances/dtc"
}
]
}
krivi37 marked this conversation as resolved.
Show resolved Hide resolved
}
}
}
Loading