List Hosted Services
Updated: June 7, 2012
The List Hosted Services operation lists the cloud services available under the current subscription.
Request
The List Hosted Services request may be specified as follows. Replace <subscription-id> with your subscription ID.
| Method | Request URI | HTTP Version |
|---|---|---|
|
GET |
|
HTTP/1.1 |
URI Parameters
None.
Request Headers
The following table describes the 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 2009-10-01 or a later version. For more information about versioning headers, see Service Management Versioning. |
Request Body
None.
Response
The response includes an HTTP status code, a set of response headers, and a response body.
Status Code
A successful operation returns status code 200 (OK). For information about status codes, see Service Management 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 comply with the HTTP/1.1 protocol specification.
| Response Header | Description |
|---|---|
|
x-ms-request-id |
A value that uniquely identifies a request made against the management service. |
Response Body
The format of the request body is as follows. Note that the XML elements must be specified in the order shown:
<?xml version="1.0" encoding="utf-8"?>
<HostedServices xmlns=”http://schemas.microsoft.com/windowsazure”>
<HostedService>
<Url>hosted-service-address</Url>
<ServiceName>hosted-service-name</ServiceName>
<HostedServiceProperties>
<Description>description</Description>
<AffinityGroup>affinity-group</AffinityGroup>
<Location>service-location</Location>
<Label>label</Label>
<Status>status</Status>
<DateCreated>date-created</DateCreated>
<DateLastModified>date-modified</DateLastModified>
<ExtendedProperties>
<ExtendedProperty>
<Name>property-name</Name>
<Value>property-value</Value>
</ExtendedProperty>
</ExtendedProperties>
</HostedServiceProperties>
</HostedService>
</HostedServices>
The following table describes the key elements of the response body.
| Element name | Description |
|---|---|
|
Url |
The Service Management API request URI used to perform Get Hosted Service Properties requests against the cloud service. |
|
ServiceName |
The name of the cloud service. This name is the DNS prefix name and can be used to access the service. For example, if the service name is MyService you could access the access the service by calling: http://MyService.cloudapp.net |
|
Description |
The description for the cloud service. The Description element is only available using version 2012-03-01 or higher. |
|
AffinityGroup |
The affinity group with which this cloud service is associated, if any. If the service is associated with an affinity group, the Location element is not returned. The AffinityGroup element is only available using version 2012-03-01 or higher. |
|
Location |
The geo-location of the cloud service in Windows Azure, if the service is not associated with an affinity group. If a location has been specified, the AffinityGroup element is not returned. The Location element is only available using version 2012-03-01 or higher. |
|
Label |
The base-64 encoded user supplied name of the cloud service. This name can be used identify the service for your tracking purposes. The Label element is only available using version 2012-03-01 or higher. |
|
Status |
The status of the cloud service. Possible values are:
The Status element is only available using version 2012-03-01 or higher. |
|
DateCreated |
The date that the cloud service was created, in [4DigitYear]-[2DigitMonth]-[2DigitDay]T[2DigitHour]:[2DigitMinute]:[2DigitSecond]Z format. The date 2011-05-11T16:15:26Z is an example that could be returned by the DateCreated or DateLastModified elements. The DateCreated element is only available using version 2012-03-01 or higher. |
|
DateLastModified |
The date that the cloud service was last updated, in [4DigitYear]-[2DigitMonth]-[2DigitDay]T[2DigitHour]:[2DigitMinute]:[2DigitSecond]Z format. The date 2011-05-11T16:15:26Z is an example that could be returned by the DateCreated or DateLastModified elements The DateLastModified element is only available using version 2012-03-01 or higher. |
|
Name |
Represents the name of an extended cloud service property. Each extended property must have both a defined name and value. You can have a maximum of 50 extended property name and value pairs. The Name element is only available using version 2012-03-01 or higher. |
|
Value |
Represents the value of an extended cloud service property. Each extended property must have both a defined name and value. You can have a maximum of 50 extended property name and value pairs, and each extended property has a maximum value of 255. The Value element is only available using version 2012-03-01 or higher. |
Authorization
Any management certificate associated with the subscription specified by <subscription-id> can be used to authenticate this operation. For additional details, see Authenticating Service Management Requests.
Remarks
Use the List Hosted Services operation to enumerate the DNS prefix names and the REST operation URI address prefixes for the cloud services in a specified subscription. The cloud service DNS prefix name is needed as a parameter for operations on certificates associated with that service.
If the x-ms-version is older than 2012-03-01, cloud services that contain virtual machine deployments will not be returned.
Example
The following example is a console application that uses the List Hosted Services operation to retrieve and display the cloud services in a specified subscription. To run the program, initialize the Thumbprint value with the thumbprint of a management certificate associated with your subscription, and set the SubscriptionId value to your subscription ID.
namespace Microsoft.WindowsAzure.ServiceManagementRESTAPI.Samples
{
using System;
using System.Collections.Generic;
using System.Net;
using System.Security.Cryptography.X509Certificates;
using System.Xml;
using System.Xml.Linq;
public class Program
{
// Set these constants with your values to run the sample.
private const string Version = "2011-10-01";
private const string Thumbprint = "management-certificate-thumbprint";
private const string SubscriptionId = "subscription-id";
static void Main(string[] args)
{
try
{
// Obtain the certificate with the specified thumbprint
X509Certificate2 certificate = GetStoreCertificate(Thumbprint);
ListHostedServicesExample(SubscriptionId, certificate, Version);
}
catch (Exception ex)
{
Console.WriteLine("Exception caught in Main:");
Console.WriteLine(ex.Message);
}
Console.Write("Press any key to continue:");
Console.ReadKey();
}
public static void ListHostedServicesExample(
string subscriptionId,
X509Certificate2 certificate,
string version)
{
string uriFormat = "https://management.core.windows.net/{0}/" +
"services/hostedservices";
Uri uri = new Uri(String.Format(uriFormat, subscriptionId));
HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(uri);
request.Method = "GET";
request.Headers.Add("x-ms-version", version);
request.ClientCertificates.Add(certificate);
request.ContentType = "application/xml";
XDocument responseBody = null;
HttpStatusCode statusCode;
HttpWebResponse response;
try
{
response = (HttpWebResponse)request.GetResponse();
}
catch (WebException ex)
{
// GetResponse throws a WebException for 400 and 500 status codes
response = (HttpWebResponse)ex.Response;
}
statusCode = response.StatusCode;
if (response.ContentLength > 0)
{
using (XmlReader reader = XmlReader.Create(response.GetResponseStream()))
{
responseBody = XDocument.Load(reader);
}
}
response.Close();
if (statusCode.Equals(HttpStatusCode.OK))
{
XNamespace wa = "http://schemas.microsoft.com/windowsazure";
XElement cloudServices = responseBody.Element(wa + "HostedServices");
Console.WriteLine(
"Cloud Services for Subscription ID {0}:{1}{2}",
subscriptionId,
Environment.NewLine,
cloudServices.ToString(SaveOptions.OmitDuplicateNamespaces));
}
else
{
Console.WriteLine("Call to List Hosted Services returned an error:");
Console.WriteLine("Status Code: {0} ({1}):{2}{3}",
(int)statusCode, statusCode, Environment.NewLine,
responseBody.ToString(SaveOptions.OmitDuplicateNamespaces));
}
return;
}
private static X509Certificate2 GetStoreCertificate(string thumbprint)
{
List<StoreLocation> locations = new List<StoreLocation>
{
StoreLocation.CurrentUser,
StoreLocation.LocalMachine
};
foreach (var location in locations)
{
X509Store store = new X509Store("My", location);
try
{
store.Open(OpenFlags.ReadOnly | OpenFlags.OpenExistingOnly);
X509Certificate2Collection certificates = store.Certificates.Find(
X509FindType.FindByThumbprint, thumbprint, false);
if (certificates.Count == 1)
{
return certificates[0];
}
}
finally
{
store.Close();
}
}
throw new ArgumentException(string.Format(
"A Certificate with Thumbprint '{0}' could not be located.",
thumbprint));
}
}
}
The code example output will resemble the following for a subscription with one cloud service:
Cloud Services for Subscription ID 01234567-89ab-cdef-0123-456789abcdef:
<HostedServices xmlns="http://schemas.microsoft.com/windowsazure" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<HostedService>
<Url>https://management.core.windows.net/01234567-89ab-cdef-0123-456789abcdef/services/hostedservices/MyHostedService1</Url>
<ServiceName>MyHostedService1</ServiceName>
</HostedService>
</HostedServices>
Press any key to continue: