put_attributes ( $domain_name, $item_name, $keypairs, $replace, $opt )

The PutAttributes operation creates or replaces attributes in an item.

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 name and attribute value are the same. Optionally, the requestor 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 requestor 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.

Using PutAttributes to replace attribute values that do not exist will not result in an error response.

You cannot specify an empty string as an attribute name.

Because Amazon SimpleDB makes multiple copies of your data and uses an eventual consistency update model, an immediate GetAttributes or Select request (read) immediately after a DeleteAttributes request (write) might not return the updated data.

The following limitations are enforced for this operation:

  • 256 attribute name-value pairs per item
  • 1 billion attributes per domain
  • 10 GB of total user data storage per domain

Access

public

Parameters

Parameter

Type

Required

Description

$domain_name

string

Required

The name of the domain in which the attributes are being deleted.

$item_name

string

Required

The name of the base item which will contain the series of keypairs.

$keypairs

array

Required

Associative array of parameters which are treated as key-value and key-multivalue pairs (i.e. a key can have one or more values; think tags).

  • [key] - array - Set the custom key name as the key for this value. For the value, pass a string for a single value, or an indexed array for multiple values.

$replace

boolean
array

Optional

Whether to replace a key-value pair if a matching key already exists. Supports either a boolean (which affects ALL key-value pairs) or an indexed array of key names (which affects only the keys specified). Defaults to boolean false.

$opt

array

Optional

An associative array of parameters that can have the following keys:

  • Expected - array - Optional - The update condition which, if specified, determines if the specified attributes will be updated or not. The update condition must be satisfied in order for this request to be processed and the attributes to be updated.
    • Name - string - Optional - The name of the attribute involved in the condition.
    • Value - string - Optional - The value of an attribute. This value can only be specified when the exists parameter is equal to true.
    • Exists - string - Optional - True if the specified attribute must exist with the specified value in order for this update condition to be satisfied, otherwise false if the specified attribute should not exist in order for this update condition to be satisfied.
  • curlopts - array - Optional - A set of values to pass directly into curl_setopt(), where the key is a pre-defined CURLOPT_* constant.
  • returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This is useful for manually-managed batch requests.

Returns

Type

Description

CFResponse

A CFResponse object containing a parsed HTTP response.

Examples

Put a series of key-value pairs to a specific item.

// Instantiate
$sdb = new AmazonSDB();
$response = $sdb->put_attributes('example-domain', 'unit-test', array(
	'key1' => 'value1',
	'key2' => array(
		'value1',
		'value2',
		'value3'
	)
));

// Success?
var_dump($response->isOK());
Result:
bool(true)

Put a series of key-value pairs to a specific item, and replace all duplicates.

// Instantiate
$sdb = new AmazonSDB();
$response = $sdb->put_attributes('example-domain', 'unit-test', array(
	'key1' => 'value1',
	'key2' => array(
		'value1',
		'value2',
		'value3'
	)
), true);

// Success?
var_dump($response->isOK());
Result:
bool(true)

Put a series of key-value pairs to a specific item, and replace all duplicates as long as conditions are met.

// Instantiate
$sdb = new AmazonSDB();
$response = $sdb->put_attributes('example-domain', 'unit-test', array(
	'key99' => 'value'
),
false, // Value for $replace
array( // Optional parameters
	'Expected' => array(
		'Name' => 'key99',
		'Value' => 'value1',
		'Exists' => 'true'
	)
));

// Success?
var_dump($response->isOK());
Result:
bool(true)

Related Methods

Source

Method defined in services/sdb.class.php | Toggle source view (20 lines) | View on GitHub

public function put_attributes($domain_name, $item_name, $keypairs, $replace = null, $opt = null)
{
    if (!$opt) $opt = array();
    $opt['DomainName'] = $domain_name;
    $opt['ItemName'] = $item_name;

    $opt = array_merge($opt, CFComplexType::map(
        self::remap_attribute_items_for_complextype($keypairs, $replace)
    ));

    if (isset($opt['Expected']))
    {
        $opt = array_merge($opt, CFComplexType::map(array(
            'Expected' => $opt['Expected']
        )));
        unset($opt['Expected']);
    }

    return $this->authenticate('PutAttributes', $opt, $this->hostname);
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback