batch_put_attributes ( $domain_name, $item_keypairs, $replace, $opt )

The BatchPutAttributes operation creates or replaces attributes within one or more items.

Attributes are uniquely identified within 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 item attribute name and item attribute value are the same.

Optionally, the requester can supply the Replace parameter for each individual value. Setting this value to true will cause the new attribute value to replace the existing attribute value(s). For example, if an item I has the attributes { 'a', '1' }, { 'b', '2'} and { 'b', '3' } and the requester does a BatchPutAttributes of {'I', 'b', '4' } with the Replace parameter set to true, the final attributes of the item will be { ‘a’, ‘1’ } and { ‘b’, ‘4’ }, replacing the previous values of the ‘b’ attribute with the new value. You cannot specify an empty string as an item or attribute name.

The BatchPutAttributes operation succeeds or fails in its entirety. There are no partial puts. You can execute multiple BatchPutAttributes operations and other operations in parallel. However, large numbers of concurrent BatchPutAttributes calls can result in Service Unavailable (503) responses. The following limitations are enforced for this operation:

  • 256 attribute name-value pairs per item
  • 1 MB request size
  • 1 billion attributes per domain
  • 10 GB of total user data storage per domain
  • 25 item limit per BatchPutAttributes operation

Access

public

Parameters

Parameter

Type

Required

Description

$domain_name

string

Required

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

$item_keypairs

array

Required

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

<

ul>

  • [item] - array - Set the custom item name as the key for this value.

    • [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:

    • Item - array - Optional - A list of items on which to perform the operation.
      • x - array - This represents a simple array index.
        • ItemName - string - Optional - This is the parameter format supported by the web service API. This is the item name to use.
        • Attribute - array - Optional - This is the parameter format supported by the web service API. This is the attribute node.
          • x - array - This represents a simple array index.
            • Name - string - Required - The name of the attribute.
            • AlternateNameEncoding - string - Optional - This is the parameter format supported by the web service API. This is the alternate name encoding to use.
            • Value - string - Required - The value of the attribute.
            • AlternateValueEncoding - string - Optional - This is the parameter format supported by the web service API. This is the alternate value encoding to use.
    • 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

    Add a series of item-key-value pairs.

    // Instantiate
    $sdb = new AmazonSDB();
    
    // Test data
    $response = $sdb->batch_put_attributes('example-domain', array(
    	'item1' => array(
    		'key1' => 'value1',
    		'key2' => array(
    			'value1',
    			'value2',
    			'value3',
    		),
    		'key3' => array('value1'),
    		'key99' => 'value1',
    	),
    	'item2' => array(
    		'key1' => 'value1',
    		'key2' => array(
    			'value1',
    			'value2',
    			'value3',
    		),
    		'key3' => array('value1'),
    	),
    	'item3' => array(
    		'key1' => 'value1',
    		'key2' => array(
    			'value1',
    			'value2',
    			'value3',
    		),
    		'key3' => array('value1'),
    	),
    ));
    
    // Success?
    var_dump($response->isOK());
    Result:
    bool(true)

    Add a series of item-key-value pairs, replacing all duplicates.

    // Instantiate
    $sdb = new AmazonSDB();
    
    // Test data
    $response = $sdb->batch_put_attributes('example-domain', array(
    	'item1' => array(
    		'key1' => 'value1',
    		'key2' => array(
    			'value1',
    			'value2',
    			'value3',
    		),
    		'key3' => array('value1'),
    	),
    	'item2' => array(
    		'key1' => 'value1',
    		'key2' => array(
    			'value1',
    			'value2',
    			'value3',
    		),
    		'key3' => array('value1'),
    	),
    	'item3' => array(
    		'key1' => 'value1',
    		'key2' => array(
    			'value1',
    			'value2',
    			'value3',
    		),
    		'key3' => array('value1'),
    	),
    ), true);
    
    // Success?
    var_dump($response->isOK());
    Result:
    bool(true)

    Related Methods

    Source

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

    public function batch_put_attributes($domain_name, $item_keypairs, $replace = null, $opt = null)
    {
        if (!$opt) $opt = array();
        $opt['DomainName'] = $domain_name;
    
        $opt = array_merge($opt, CFComplexType::map(
            self::remap_batch_items_for_complextype($item_keypairs, $replace)
        ));
    
        if (isset($opt['Item']))
        {
            $opt = array_merge($opt, CFComplexType::map(array(
                'Item' => $opt['Item']
            )));
            unset($opt['Item']);
        }
    
        return $this->authenticate('BatchPutAttributes', $opt, $this->hostname);
    }

    Copyright © 2010–2013 Amazon Web Services, LLC


    Feedback