Using the SOAP API

You can access Amazon CloudWatch using the SOAP web services messaging protocol. This interface is described by a Web Services Description Language (WSDL) document, which defines the operations and security model for the particular service. The WSDL references an XML Schema document, which strictly defines the data types that might appear in SOAP requests and responses. For more information on WSDL and SOAP, see Web Services References.

	Note
	Amazon CloudWatch supports SOAP only through HTTPS.

All schemas have a version number. The version number appears in the URL of a schema file and in a schema's target namespace. This makes upgrading easy by differentiating requests based on the version number.

Since the SOAP requests and responses in Amazon CloudWatch follow current standards, nearly any programming language can be used.

Note

AWS provides libraries, sample code, tutorials, and other resources for software developers who prefer to build applications using language-specific APIs instead of Amazon CloudWatch's SOAP and Query APIs. These libraries provide basic functions (not included in Amazon CloudWatch's SOAP and Query APIs), such as request authentication, request retries, and error handling so that it's easier to get started. Libraries and resources are available for the following languages: Java PHP Ruby Windows and .NET For libraries and sample code in all languages, go to Sample Code & Libraries.

Amazon CloudWatch requires you to hash and sign SOAP requests with the current WS-Security standard, requiring SOAP request messages to be hashed and signed for integrity and non-repudiation. WS-Security defines profiles which are used to implement various levels of security. Amazon CloudWatch secure SOAP messages use the BinarySecurityToken profile, consisting of an X.509 certificate with an RSA public key.

The following is the content of an insecure GetMetricStatistics operation:

<GetMetricStatistics xmlns="http://monitoring.amazonaws.com/doc/2009-05-15/">
	<Statistics>
		<member>Average</member>
	</Statistics>
	<Period>60</Period>
	<MeasureName>CPUUtilization</MeasureName>
	<Dimensions>
		<member>
			<Name>InstanceType</Name>
			<Value>m1.small</Value>
		</member>
		<member>
			<Name>ImageID</Name>
			<Value>ami-11ca2d78</Value>
		</member>
	</Dimensions>
	<StartTime>2009-05-14T19:12:59Z</StartTime>
	<EndTime>2009-05-14T19:15:01Z<EndTime>
</GetMetricStatistics>
			
		

To secure the request, we add the BinarySecurityToken element.

The secure version of the request begins with the following:

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<soap:Header>...</soap:Header>
 <soap:Body wsu:Id="id-19451103" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
 <GetMetricStatistics xmlns="http://monitoring.amazonaws.com/doc/2009-05-15/">
	<Statistics>
		<member>Average</member>
	</Statistics>
	<Period>60</Period>
	<measure name>CPUUtilization</measure name>
	<Dimensions>
		<member>
			<Name>InstanceType</Name>
			<Value>m1.small</Value>
		</member>
		<member>
			<Name>ImageID</Name>
			<Value>ami-11ca2d78</Value>
		</member>
	</Dimensions>
	<StartTime>2009-05-14T19:12:59Z</StartTime>
	<EndTime>2009-05-14T19:15:01Z<EndTime>
</GetMetricStatistics>
</soap:Body>
</soap:Envelope>
	
			

If you are matching this against requests generated by Amazon CloudWatch supplied libraries, or those of another vendor, the following are the most important elements:

In response to a request, Amazon CloudWatch returns an XML data structure that conforms to an XML schema defined as part of the Amazon CloudWatch WSDL. The structure of a XML response is specific to the associated request. In general, the response data types are named according to the operation performed and whether the data type is a container (can have children). Examples of containers include groupSet for security groups and instancesSet for instances. Item elements are children of containers and their contents vary according to the container's role.

<?xml version="1.0" encoding="UTF-8"?>
<Envelope encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns="http://schemas.xmlsoap.org/soap/envelope/">
	<Header>...</Header>
		<Body>
			<GetMetricStatisticsResponse xmlns="http://monitoring.amazonaws.com/doc/2009-05-15/">
			<GetMetricStatisticsResult>
				<Label xmlns="http://monitoring.amazonaws.com/doc/2009-05-15/">CPUUtilization</Label>
				<Datapoints>
					<member>
						<Timestamp>2009-05-14T19:13:00Z</Timestamp>
						<Unit>Percent</Unit>
						<Samples>1.0</Samples>
						<Average>0.0</Average>
					</member>
					<member>
						<Timestamp>2009-05-14T19:12:00Z</Timestamp>
						<Unit>Percent</Unit>
						<Samples>1.0</Samples>
						<Average>0.0</Average>
					</member>
				</Datapoints>
			</GetMetricStatisticsResult>
		<ResponseMetadata>
			<RequestId>892070df</RequestId>
		</ResponseMetadata>
		</GetMetricStatisticsResponse>
	</Body>
</Envelope> 

		

For more information about using web services, go to any of the following resources: