Creating Servers
The Create Server operation adds a new SQL Database server to a subscription.
Request
The Create Server request must be specified as follows. Replace <subscription-id> with your subscription ID.
| Method | Request URI | HTTP Version |
|---|---|---|
|
POST |
https://management.database.windows.net:8443/<subscription-id>/servers |
HTTP/1.1 |
URI Parameters
No URL parameters used with this operation.
Request Headers
The following table describes the required and optional request headers.
| Request Header | Description |
|---|---|
|
x-ms-version |
Required. Specifies the version of the operation to use for this request. This header should be set to 1.0. |
Request Body
The format of the request body is as follows:
<?xml version="1.0" encoding="utf-8"?> <Server xmlns=”http://schemas.microsoft.com/sqlazure/2010/12/”> <AdministratorLogin>MyAdminAccount</AdministratorLogin> <AdministratorLoginPassword>MyAdminPassword</AdministratorLoginPassword> <Location>East US | North Central US | South Central US | West US | North Europe | West Europe | East Asia | Southeast Asia</Location> </Server>
Sample Request
The following is an example request body:
<?xml version="1.0" encoding="utf-8"?> <Server xmlns=”http://schemas.microsoft.com/sqlazure/2010/12/”> <AdministratorLogin>MyAdminAccount</AdministratorLogin> <AdministratorLoginPassword>My@dminPa$$w0rd123ABC</AdministratorLoginPassword> <Location>North Central US</Location> </Server>
Response
The response includes an HTTP status code, a set of response headers, and a response body.
Status Code
A successful Create Server operation will return HTTP status code 201 (Created).
Potential errors for this operation include the errors listed in the following table.
| Error code | HTTP status code | User Message |
|---|---|---|
|
15006 |
Bad Request (400) |
<AdministratorLogin> is not a valid name because it contains invalid characters. |
|
40630 |
Bad Request (400) |
Password validation failed. The password does not meet policy requirements because it is too short. |
|
40631 |
Bad Request (400) |
The password that you specified is too long. The password should have no more than 128 characters. |
|
40632 |
Bad Request (400) |
Password validation failed. The password does not meet policy requirements because it is not complex enough. |
|
40638 |
Bad Request (400) |
Invalid subscription id <subscription-id>. Subscription does not exist. |
|
40639 |
Bad Request (400) |
Request does not conform to schema: <schema error>. |
|
40640 |
Internal Server Error (500) |
The server encountered an unexpected exception. |
|
40641 |
Bad Request (400) |
The specified location is invalid. |
|
40642 |
Service Unavailable (503) |
The server is currently too busy. Please try again later. |
|
40643 |
Bad Request (400) |
The specified x-ms-version header value is invalid. |
|
40644 |
Forbidden (403) |
Failed to authorize access to the specified subscription. |
|
40648 |
Service Unavailable (503) |
Too many requests have been performed. Please retry later. |
|
40649 |
Bad Request (400) |
Invalid content-type is specified. Only application/xml is supported. |
|
40650 |
Bad Request (400) |
Subscription <subscription-id> does not exist or is not ready for the operation. |
|
40651 |
Bad Request (400) |
Failed to create server because the subscription <subscription-id> is disabled. |
|
40652 |
Bad Request (400) |
Cannot move or create server. Subscription <subscription-id> will exceed server quota. |
For more information about status codes for the SQL Database Management API, see Status and Error Codes.
Response Headers
The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
| Response Header | Description |
|---|---|
|
x-ms-request-id |
A value that uniquely identifies a request made against the database management service. This request id is used for request tracking. If a failure occurs that requires the user to contact Microsoft Support, the request id should be provided to Microsoft to assist in tracking and resolving the failure for the request. The SQL Database Management API does not support asynchronous calls. |
Response Body
The format of the response body is as follows:
<?xml version="1.0" encoding="utf-8"?> <ServerName xmlns="http://schemas.microsoft.com/sqlazure/2010/12/">TheNewServerName</ServerName>
Sample Response
The following is an example response body:
<?xml version="1.0" encoding="utf-8"?> <ServerName xmlns="http://schemas.microsoft.com/sqlazure/2010/12/">zpc0fbxur0</ServerName>
Code Example
The following code provides a simple example for calling this operation from a C# console application. This code uses the System.Net.HttpWebRequest and System.Security.Cryptography.X509Certificate2 class to submit the request using the private key certificate.
using System; using System.Collections.Generic; using System.Linq; using System.Text; using System.Net; using System.Security.Cryptography.X509Certificates; using System.IO; using System.Xml; namespace SQLAzureDatabaseManagement { class Program { static void Main(string[] args) { string certFile; string certPassword; string subscriptionId; string AdminAcct; string AdminPwd; string Location; if (args.Length != 6) { Console.WriteLine("\nInsufficient Arguments.\n\nExpected CertfilePath, CertfilePassword, SubscriptionID, Admin, AdminPassword, and Location.\n"); return; } else { certFile = args[0]; certPassword = args[1]; subscriptionId = args[2]; AdminAcct = args[3]; AdminPwd = args[4]; Location = args[5]; } //=========================================================================// //=== Execute SQL Database Server and Firewall Rules Management Operations ===// //=========================================================================// // Create a new server CreateServer(certFile, certPassword, subscriptionId, AdminAcct, AdminPwd, Location); } //===============================================================================================================// //=== ===// //=== CreateServer ===// //=== ===// //=== This function should create a new SQL Database server under the specified subscription, and return the new ===// //=== server's name as output written to the console. ===// //=== ===// //=== Input Parameters: ===// //=== ===// //=== string certFilename : Full path to the Personal Information Exchange (.pfx) file which holds the ===// //=== private key for the certificate. The public key file must already be associated ===// //=== to the subscription. ===// //=== ===// //=== string certPassword : The password of the Personal Information Exchange (.pfx) file referenced by ===// //=== certFilename. ===// //=== ===// //=== string subscriptionId : This is the subscription id GUID in its string form. ===// //=== ===// //=== string Admin : The Administrator account for the new server. ===// //=== ===// //=== string AdminPwd : This is the Administrator password for the new server which is associated with the ===// //=== Administrator account (Admin). ===// //=== ===// //=== string Location : This location string should match a valid location for the Location element in the ===// //=== Server.xsd schema (http://schemas.microsoft.com/sqlazure/2010/12/ Server.xsd). ===// //=== ===// //=== Output: ===// //=== ===// //=== The output of this function is written to the console. The output includes: ===// //=== ===// //=== The subscription id passed to this function. ===// //=== ===// //=== The request body built using the parameters passed to this function. ===// //=== ===// //=== The x-ms-request-id header returned from the REST API call. ===// //=== ===// //=== The HTTP Status code returned from the REST API call. ===// //=== ===// //=== The "ServerName" element returned from the response body of the REST API call or the exception ===// //=== and error encountered during the REST API call. ===// //=== ===// //===============================================================================================================// static void CreateServer(string certFilename, string certPassword, string subscriptionId, string Admin, string AdminPwd, string Location) { Console.WriteLine("\n============================"); Console.WriteLine("=== CreateServer Request ==="); Console.WriteLine("============================\n"); Console.WriteLine("Subscription : {0} \n", subscriptionId); try { string url = string.Format("https://management.database.windows.net:8443/{0}/servers", subscriptionId); HttpWebRequest webRequest = HttpWebRequest.Create(url) as HttpWebRequest; webRequest.ClientCertificates.Add(new X509Certificate2(certFilename, certPassword)); webRequest.Headers["x-ms-version"] = "1.0"; webRequest.Method = "POST"; //=== Add the Request Payload ===// string xmlBody = "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n" + "<Server xmlns=\"http://schemas.microsoft.com/sqlazure/2010/12/\">\n" + " <AdministratorLogin>" + Admin.ToString() + "</AdministratorLogin>\n" + " <AdministratorLoginPassword>" + AdminPwd.ToString() + "</AdministratorLoginPassword>\n" + " <Location>" + Location.ToString() + "</Location>\n" + "</Server>"; Console.WriteLine("Request Body for the CreateServer Request : ...\n"); Console.WriteLine(xmlBody); byte[] bytes = Encoding.UTF8.GetBytes(xmlBody); webRequest.ContentLength = bytes.Length; webRequest.ContentType = "application/xml;charset=utf-8"; using (Stream requestStream = webRequest.GetRequestStream()) { requestStream.Write(bytes, 0, bytes.Length); } //=== Send the request and wait on the response ===// using (WebResponse webResponse = webRequest.GetResponse()) { //=== x-ms-request-id is useful for troubleshooting request failures with Microsoft ===// Console.WriteLine("\nResponse x-ms-request-id : {0}", webResponse.Headers["x-ms-request-id"]); Console.WriteLine("HttpStatusCode = {0}\n", (int)((HttpWebResponse)webResponse).StatusCode); using (Stream stream = webResponse.GetResponseStream()) { using (XmlTextReader xmlReader = new XmlTextReader(stream)) { while (xmlReader.Read()) { switch (xmlReader.NodeType) { case XmlNodeType.Element: if (xmlReader.Name == "ServerName") { if (xmlReader.Read() && (xmlReader.NodeType == XmlNodeType.Text)) { Console.WriteLine("NewServerName : {0}\n", xmlReader.Value.ToString()); } } break; } } } } } } //====================================================================================// //=== Catch WebExceptions. The SQL Database Management Service will ===// //=== provide detailed error information in the response stream for WebExceptions. ===// //====================================================================================// catch (WebException webEx) { Console.WriteLine("WebException : \n\n" + webEx.ToString()); try { HttpWebResponse errorResponse = (HttpWebResponse)webEx.Response; Console.WriteLine(string.Format("HttpStatusCode = {0}", (int)errorResponse.StatusCode)); using (Stream errorResponseStream = errorResponse.GetResponseStream()) { using (StreamReader sr = new StreamReader(errorResponseStream)) { Console.WriteLine(sr.ReadToEnd()); } } } catch (Exception innerEx) { Console.WriteLine(innerEx.ToString()); Console.WriteLine(innerEx.StackTrace.ToString()); } } catch (Exception ex) { Console.WriteLine(ex.ToString() + "\n"); Console.WriteLine(ex.StackTrace.ToString() + "\n"); if (ex.InnerException != null) { Console.WriteLine(ex.InnerException.ToString() + "\n"); Console.WriteLine(ex.InnerException.StackTrace.ToString() + "\n"); } } } } }
Building the Example Code
The example code can be added to a console application project and built in the Visual Studio Integrated Development Environment (IDE), or you can compile from the command line of a command prompt using the Visual C# compiler which is also included with the .NET Framework.
In this build shown below, the code was copied into a new text file named CreateServer.cs and compiled from the command line. This build also generates debugging information.
C:\Test>C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc /debug /out:CreateServer.exe CreateServer.cs Microsoft (R) Visual C# 2010 Compiler version 4.0.30319.1 Copyright (C) Microsoft Corporation. All rights reserved. C:\Test>dir Volume in drive C has no label. Volume Serial Number is 5471-ED89 Directory of C:\Test 02/15/2011 01:38 PM <DIR> . 02/15/2011 01:38 PM <DIR> .. 02/15/2011 01:38 PM 8,192 CreateServer.exe 02/15/2011 01:38 PM 13,824 CreateServer.pdb
Executing the Example Code
The following example executes the example code using the private key certificate MyCert.pfx for authentication. The public key certificate (MyCert.cer) has already been added to the subscription. For more information on authentication, see Authenticating Windows Azure SQL Database Management API Requests.
The globally unique identifier 2eae7c21-ffd1-49e4-ac22-39095e0b9f02 is an example Windows Azure subscription id. Execution of the example code provisions a new SQL Database server, l1ej7qgrem, in the “North Central US” location for the subscription. The Administrator account for the new server is “MyAdmin” and “My@dminPa$$word123$” is the administrative password.
C:\Test>CreateServer.exe C:\SecureStore\MyCert.pfx MyCertPassword 2eae7c21-ffd1-49e4-ac22-39095e0b9f02 MyAdmin My@dminPa$$word123$$ "North Central US" ============================ === CreateServer Request === ============================ Subscription : 2eae7c21-ffd1-49e4-ac22-39095e0b9f02 Request Body for the CreateServer Request : ... <?xml version="1.0" encoding="utf-8"?> <Server xmlns="http://schemas.microsoft.com/sqlazure/2010/12/"> <AdministratorLogin>MyAdmin</AdministratorLogin> <AdministratorLoginPassword>My@dminPa$$word123$$</AdministratorLoginPassword> <Location>North Central US</Location> </Server> Response x-ms-request-id : f5d3b9d7-c515-479d-876a-d0824d55fd19 HttpStatusCode = 201 NewServerName : l1ej7qgrem
See Also