Working with Attributes in Amazon SimpleDB

Overview

The following operations allow you to work with attributes. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with attributes, see Sample configuration.

Operation details

This section provides details on the operations.

Retrieving attributes of an item

The getAttributes operation returns all the attributes associated with the item. Optionally, the attributes returned can be limited to one or more specified attribute name parameters. 

Amazon SimpleDB stores multiple copies of each domain. When data is written or updated, all copies of the data are updated. However, it takes time for the update to propagate to all storage locations. The data will eventually be consistent, but an immediate read might not show the change. If the item does not exist on the replica that was accessed for this operation, an empty set is returned.

<amazonsdb.getAttributes>
	<domainName>{$ctx:domainName}</domainName>
    <itemName>{$ctx:itemName}</itemName>
   	<attributeNames>{$ctx:attributeNames}</attributeNames>
    <consistentRead>{$ctx:consistentRead}</consistentRead>
</amazonsdb.getAttributes> 

Properties

• domainName: Required - The name of the domain in which to perform the operation.
• itemName: Required - The name of the item. 
• attributeNames: Optional - The names of the attributes to return. If you do not specify any attribute names, all the attributes for the item are returned.
• consistentRead: Optional - When set to true, ensures that the most recent data is returned. For more information, see Consistency. Defaults to false.

Sample request

Following is a sample REST/XML request that can be handled by the getAttributes operation.

<root>
	<apiUrl>https://sdb.amazonaws.com</apiUrl>
	<accessKeyId>AKIAIYMUdsfNCUHQJEFMURA</accessKeyId>
	<secretAccessKey>qAb5n5hAYzpgcD2+7APusdfsEVg3rLtpkkEuTj2zjGOg</secretAccessKey>
	<action>GetAttributes</action>
	<version>2009-04-15</version>
	<signatureVersion>2</signatureVersion>
	<signatureMethod>HmacSHA1</signatureMethod>
	<domainName>Test</domainName>
	<itemName>User</itemName>
	<attributeNames>AttributeName.1=where&amp;AttributeName.2=with</attributeNames>
	<consistentRead>true</consistentRead>
</root> 

Related Amazon SimpleDB documentation

http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/SDB_API_GetAttributes.html

 Creating or replacing attributes in an item

The putAttributes operation creates or replaces attributes in an item. You can create a conditional update by specifying an expected attribute name and value that must be matched (or specify that a specific attribute must exist or not exist) for the update to occur. This approach is useful for ensuring multiple processes do not overwrite each other.

<amazonsdb.putAttributes>
	<itemName>{$ctx:itemName}</itemName>
    <expectedValue>{$ctx:expectedValue}</expectedValue>
    <domainName>{$ctx:domainName}</domainName>
    <expectedExists>{$ctx:expectedExists}</expectedExists>
    <attributes>{$ctx:attributes}</attributes>
    <expectedName>{$ctx:expectedName}</expectedName>
</amazonsdb.putAttributes>	

Properties

• itemName: Required - The name of the item. 
• expectedValue: Conditional - Value of the attribute to check. If the attribute contains the expected value, the operation is performed. You must specify the attribute name using expectedName. You cannot use this operation when expectedExists is set to false. The expectedValue operation can only be used with single-valued attributes.
• domainName: Required - The name of the domain in which to perform the operation.
• expectedExists: Conditional - Specifies whether to test the existence of an attribute while performing conditional updates. You must specify the attribute name using expectedName, and when expectedExists is set to true, you must also specify expectedValue. If expectedExists is set to false, you cannot use expectedValue, and the operation will be performed only if the attribute does not exist. The expectedExists operation can only be used with single-valued attributes.
• attributes: Required - The names and values of the attributes, and optionally the Replace flag (see Attributes section below).
• expectedName: Conditional - Name of the attribute to check when performing conditional updates. This property is required when using expectedValue or expectedExists.

Attributes

New attributes are specified using a combination of the Attribute.X.Name and Attribute.X.Value parameters. You specify the first attribute by the parameters Attribute.1.Name  and  Attribute.1.Value, the second attribute by the parameters Attribute.2.Name and Attribute.2.Value, and so on.

Attributes are uniquely identified in an item by their name/value combination. For example, a single item can have the attributes "first_name", "first_value" and "first_name", "second_value". However, it cannot have two attribute instances where both the Attribute.X.Name and Attribute.X.Value are the same.

Optionally, the requester can supply the Replace parameter for each individual attribute. Setting this value to true causes the new attribute value to replace the existing attribute value(s). For example, if an item has the attributes {'a', '1'}, {'b', '2'} and {'b', '3'} and the requester calls putAttributes using the attributes {'b', '4'} with the Replace parameter set to true, the final attributes of the item are changed to {'a', '1'} and {'b', '4'}, which replaces the previous values of the 'b' attribute with the new value.

Sample request

Following is a sample REST/XML request that can be handled by the putAttributes operation.

<root>
	<apiUrl>https://sdb.amazonaws.com</apiUrl>
	<accessKeyId>AKIAIYMUNCUdfHQJEFMURA</accessKeyId>
	<secretAccessKey>qAb5n5hAYzpgcD2+7APuEVg3rLtpkkdgdEuTj2zjGOg</secretAccessKey>
	<action>PutAttributes</action>
	<version>2009-04-15</version>
	<signatureVersion>2</signatureVersion>
	<signatureMethod>HmacSHA1</signatureMethod>
	<domainName>User</domainName>
	<itemName>Item</itemName>
	<attributes>Attribute.1.Name=gift&amp;Attribute.1.Value=new&amp;Attribute.1.Replace=true</attributes>
	<expectedName>gift</expectedName>
	<expectedValue>ted</expectedValue>
	<expectedExists></expectedExists>
</root>

Related Amazon SimpleDB documentation

http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/SDB_API_PutAttributes.html

 Deleting attributes of an item

The deleteAttributes operation deletes one or more attributes associated with the item. If all attributes of an item are deleted, the item is deleted. If an attribute has multiple values, you can specify the values you want to delete from that attribute, or delete the attribute and all its values by specifying just its name.

<amazonsdb.deleteAttributes>
	<domainName>{$ctx:domainName}</domainName>
	<itemName>{$ctx:itemName}</itemName>
    <attributes>{$ctx:attributes}</attributes>
	<expectedName>{$ctx:expectedName}</expectedName>
	<expectedValue>{$ctx:expectedValue}</expectedValue>        
    <expectedExists>{$ctx:expectedExists}</expectedExists>        
</amazonsdb.deleteAttributes>

Properties

• domainName: Required - The name of the domain in which to perform the operation.
• itemName: Required - The name of the item. 
• attributes: The attributes to delete. If you do not specify any attribute names, the item and all its attributes are deleted. If you specify one or more attribute names, just those specified attributes are deleted from the item. For multi-value attributes, you can specify the attribute name and the values you want to delete from that attribute, which deletes just those values from the attribute without deleting the attribute itself.
• expectedName: Conditional - Name of the attribute to check when performing conditional deletes. This property is required when using expectedValue or expectedExists.
• expectedValue: Conditional - Value of the attribute to check. If the attribute contains the expected value, the operation is performed. You must specify the attribute name using expectedName. You cannot use this operation when expectedExists is set to false. The expectedValue operation can only be used with single-valued attributes.
• expectedExists: Conditional - Specifies whether to test the existence of an attribute while performing conditional deletes. You must specify the attribute name using expectedName, and when expectedExists is set to true, you must also specify expectedValue. If expectedExists is set to false, you cannot use expectedValue, and the operation will be performed only if the attribute does not exist. The expectedExists operation can only be used with single-valued attributes.

Sample request

Following is a sample REST/XML request that can be handled by the deleteAttributes operation.

<root>
	<apiUrl>https://sdb.amazonaws.com</apiUrl>
	<accessKeyId>AKIAIYMUNdgCUHQJEFMURA</accessKeyId>
	<secretAccessKey>qAb5n5hAYzpgcD2+7APuEVg3dgrLtpkkEuTj2zjGOg</secretAccessKey>
	<action>DeleteAttributes</action>
	<version>2009-04-15</version>
	<signatureVersion>2</signatureVersion>
	<signatureMethod>HmacSHA1</signatureMethod>
	<domainName>User</domainName>
	<itemName>Item</itemName>
	<attributes>Attribute.1.Name=new_where&amp;Attribute.1.Value=KFC</attributes>
</root>

Related Amazon SimpleDB documentation

http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/SDB_API_DeleteAttributes.html

Sample request

Following is a sample REST/XML request that can be handled by the batchDeleteAttributes operation.

<root>
	<apiUrl>https://sdb.amazonaws.com</apiUrl>
	<accessKeyId>AKIAIYMUNdgCUHQJEFMURA</accessKeyId>
	<secretAccessKey>qAb5n5hAYzpgcD2+7APuEVg3dgrLtpkkEuTj2zjGOg</secretAccessKey>
	<action>DeleteAttributes</action>
	<version>2009-04-15</version>
	<signatureVersion>2</signatureVersion>
	<signatureMethod>HmacSHA1</signatureMethod>
	<domainName>user</domainName>
    <attributes>Item.1.ItemName=Shirt1&amp;Item.1.Attribute.1.Name=color&amp;Item.1.Attribute.1.Value=Blue&amp;Item.1.Attribute.1.Replace=true</attributes> 
</root>

Related Amazon SimpleDB documentation

http://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/SDB_API_BatchDeleteAttributes.html

Sample configuration

Following is a sample proxy service that illustrates how to connect to Amazon SimpleDB with the init operation and use the getAttributes operation. The sample request for this proxy can be found in getAttributes sample request. You can use this sample as a template for using other operations in this category.

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="amazonSimpleDB_getAttributes"
       transports="https,http"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
      <inSequence onError="faultHandlerSeq">
		  <property name="apiUrl" expression="//apiUrl/text()"/>
		  <property name="accessKeyId" expression="//accessKeyId/text()"/>
		  <property name="secretAccessKey" expression="//secretAccessKey/text()"/>
		  <property name="action" expression="//action/text()"/>
		  <property name="domainName" expression="//domainName/text()"/>
		  <property name="version" expression="//version/text()"/>
		  <property name="signatureVersion" expression="//signatureVersion/text()"/>
		  <property name="signatureMethod" expression="//signatureMethod/text()"/>
		  <property name="itemName" expression="//itemName/text()"/>
         <property name="attributeNames" expression="//attributeNames/text()"/>
         <property name="consistentRead" expression="//consistentRead/text()"/>		 
         <amazonsdb.init>
            <signatureMethod>{$ctx:signatureMethod}</signatureMethod>
            <secretAccessKey>{$ctx:secretAccessKey}</secretAccessKey>
            <action>{$ctx:action}</action>
            <accessKeyId>{$ctx:accessKeyId}</accessKeyId>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <signatureVersion>{$ctx:signatureVersion}</signatureVersion>
            <version>{$ctx:version}</version>
         </amazonsdb.init>
         <amazonsdb.getAttributes>
            <domainName>{$ctx:domainName}</domainName>
            <itemName>{$ctx:itemName}</itemName>
            <attributeNames>{$ctx:attributeNames}</attributeNames>
            <consistentRead>{$ctx:consistentRead}</consistentRead>
         </amazonsdb.getAttributes>
         <respond/>
      </inSequence>
      <outSequence>
          <send/>
      </outSequence>
	        <faultSequence>
         <makefault version="soap11">
            <code expression="get-property('ERROR_CODE')"/>
            <reason expression="get-property('ERROR_MESSAGE')"/>
            <detail expression="get-property('ERROR_DETAIL')"/>
         </makefault>
         <send/>
      </faultSequence>
   </target>
   <description/>
</proxy>