Enumerating Server-Level Firewall Rules
The Get Server Firewall Rules operation retrieves a list of all the server-level firewall rules for a SQL Database server that belongs to a subscription.
Request
The Get Server Firewall Rules request must be specified as follows. Replace <subscription-id> with your subscription ID, and <servername> with the name of the server that will have its list of server-level firewall rules returned.
| Method | Request URI | HTTP Version |
|---|---|---|
|
GET |
https://management.database.windows.net:8443/<subscription-id>/servers/<servername>/firewallrules |
HTTP/1.1 |
URL 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 Get Server Firewall Rules operation does not use a request body.
Response
The response includes an HTTP status code, a set of response headers, and a response body.
Status Code
A successful Get Server Firewall Rules operation will return HTTP status code 200 (Success).
Potential errors for this operation include the errors listed in the following table.
| Error code | HTTP status code | User Message |
|---|---|---|
|
40638 |
Bad Request (400) |
Invalid subscription id <subscription-id>. Subscription does not exist. |
|
40640 |
Internal Server Error (500) |
The server encountered an unexpected exception. |
|
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. |
|
40645 |
Bad Request (400) |
Servername <servername> cannot be empty or null. It can only be made up of lowercase letters 'a'-'z', the numbers 0-9 and the hyphen. The hyphen may not lead or trail in the name. |
|
40646 |
Bad Request (400) |
Subscription ID cannot be empty. |
|
40647 |
Bad Request (400) |
Subscription <subscription-id> does not have server <servername>. |
|
40648 |
Service Unavailable (503) |
Too many requests have been performed. Please retry later. |
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:
<FirewallRules xmlns="http://schemas.microsoft.com/sqlazure/2010/12/">
<FirewallRule>
<Name>Firewall Rule Name</Name>
<StartIpAddress>Start IP Addesss Range</StartIpAddress>
<EndIpAddress>End IP address Range</EndIpAddress>
</FirewallRule>
</FirewallRules>
Sample Response
The following is an example response body:
<FirewallRules xmlns="http://schemas.microsoft.com/sqlazure/2010/12/">
<FirewallRule>
<Name>Test_Firewall_Rule</Name>
<StartIpAddress>10.20.30.0</StartIpAddress>
<EndIpAddress>10.20.30.100</EndIpAddress>
</FirewallRule>
</FirewallRules>
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 ServerName; if (args.Length != 4) { Console.WriteLine("\nInsufficient Arguments.\n"); Console.WriteLine("Expected CertfilePath, CertfilePassword, SubscriptionID, and ServerName.\n"); return; } else { certFile = args[0]; certPassword = args[1]; subscriptionId = args[2]; ServerName = args[3]; } //=========================================================================// //=== Execute SQL Database Server and Firewall Rules Management Operations ===// //=========================================================================// // List the Server-Level Firewall rules for a server GetServerFirewallRules(certFile, certPassword, subscriptionId, ServerName); } //===============================================================================================================// //=== ===// //=== GetServerFirewallRules ===// //=== ===// //=== This function returns a list of all the server-level firewall rules for the specified SQL Database server. ===// //=== ===// //=== 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 on the Personal Information Exchange (.pfx) file. ===// //=== ===// //=== string subscriptionId : This is the subscription id GUID in its string form. ===// //=== ===// //=== string Server : The SQL Database server that will have its server-level firewall rules returned. ===// //=== ===// //=== Output: ===// //=== ===// //=== The output of this function is written to the console. The output includes: ===// //=== ===// //=== The subscription id passed to this function. ===// //=== ===// //=== The server name 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 response body returned from the REST API call that contains the server-level firewall rule list. ===// //=== ===// //===============================================================================================================// static void GetServerFirewallRules(string certFilename, string certPassword, string subscriptionId, string Server) { Console.WriteLine("\n======================================"); Console.WriteLine("=== GetServerFirewallRules Request ==="); Console.WriteLine("======================================\n"); Console.WriteLine("Subscription : {0}", subscriptionId); Console.WriteLine("Server : {0}\n", Server); try { string url = string.Format("https://management.database.windows.net:8443/{0}/servers/{1}/firewallrules", subscriptionId, Server); HttpWebRequest webRequest = HttpWebRequest.Create(url) as HttpWebRequest; webRequest.ClientCertificates.Add(new X509Certificate2(certFilename, certPassword)); webRequest.Headers["x-ms-version"] = "1.0"; webRequest.Method = "GET"; //=== No Request Payload needed to return server-level firewall rule list ===// using (WebResponse webResponse = webRequest.GetResponse()) { //=== x-ms-request-id is useful for troubleshooting request failures with Microsoft ===// Console.WriteLine("Response 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 (StreamReader sr = new StreamReader(stream)) { Console.WriteLine(sr.ReadToEnd()); } } } } //====================================================================================// //=== Catch WebExceptions. The SQL Database Management Service will ===// //=== provide detailed error information in the response stream for WebExceptions. ===// //====================================================================================// catch (WebException webEx) { HttpWebResponse errorResponse = (HttpWebResponse)webEx.Response; Console.WriteLine(string.Format("HttpStatusCode = {0}", (int)errorResponse.StatusCode)); try { using (Stream errorResponseStream = errorResponse.GetResponseStream()) { using (StreamReader sr = new StreamReader(errorResponseStream)) { Console.WriteLine(sr.ReadToEnd()); } } } catch (Exception innerEx) { Console.WriteLine(innerEx.ToString()); } } catch (Exception ex) { Console.WriteLine(ex.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 GetServerFirewallRules.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:GetServerFirewallRules.exe GetServerFirewallRules.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 07:00 PM <DIR> . 02/15/2011 07:00 PM <DIR> .. 02/15/2011 07:00 PM 6,656 GetServerFirewallRules.exe 02/15/2011 07:00 PM 13,824 GetServerFirewallRules.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. This subscription already has the SQL Database server, l1ej7qgrem, provisioned for it. The command shown below sends the request to return all the server-level firewall rules controlling access to that server. The XML shown is the response containing one server-level firewall rule named TestFirewallRule.
C:\Test>GetServerFirewallRules C:\SecureStore\MyCert.pfx MyCertPassword 2eae7c21-ffd1-49e4-ac22-39095e0b9f02 l1ej7qgrem
======================================
=== GetServerFirewallRules Request ===
======================================
Subscription : 2eae7c21-ffd1-49e4-ac22-39095e0b9f02
Server : l1ej7qgrem
Response x-ms-request-id : 29e68b38-ed6f-4a59-b10e-de4e14068c26
HttpStatusCode = 200
<FirewallRules xmlns="http://schemas.microsoft.com/sqlazure/2010/12/">
<FirewallRule>
<Name>TestFirewallRule</Name>
<StartIpAddress>10.20.30.0</StartIpAddress>
<EndIpAddress>10.20.30.255</EndIpAddress>
</FirewallRule>
</FirewallRules>
See Also