Update Entity

Update Entity

Switch on low bandwidth view

Collapse All

Language Filter

Windows Azure SDK, Community Technology Preview

Update Entity

[This is preliminary documentation and is subject to change.]

This operation updates an existing entity in a table. The Update Entity operation replaces the entire entity and can be used to remove properties.

Request

The Update Entity request may be constructed as follows. Replace myaccount with the name of your storage account, mytable with the name of your table, and myPartitionKey and myRowKey1 with the name of the partition key and row key identifying the entity to be updated:

Method	Request URI	HTTP Version
PUT	http://myaccount.table.core.windows.net/mytable(PartitionKey="myPartitionKey", RowKey="myRowKey1")	HTTP/1.1

The address of the entity to be updated may take a number of forms on the request URI. The way to address an entity is specified by the ADO.NET Data Services Framework. For more information, see URI Format for Addressing Resources (ADO.NET Data Services Framework).

Development Storage URI

When making a request against development storage, specify the local hostname and Table service port as 127.0.0.1:10002, followed by the development storage account name:

Method	Request URI	HTTP Version
PUT	http://127.0.0.1:10002/devstoreaccount1/mytable(PartitionKey="myPartitionKey", RowKey="myRowKey1")	HTTP/1.1

The Table service in development storage differs from the Windows Azure Table service in the following ways:

The local Table service requires configuration of fixed schema tables prior to use. The Windows Azure Table service does not require table configuration.
The local Table service supports only Shared Key Lite authentication. It does not support Shared Key authentication.
The local Table service does not support dynamic creation or deletion of tables.
The local Table service does not support creating entities with varying numbers and types of properties within the same table. The local service requires that you use the ADO.NET client library to work with tables that have a fixed schema dictated by the classes you use.
String properties in the local Table service are limited to 1,000 characters.
Date properties support only the range supported by Microsoft® SQL Server™ (that is, they are required to be later than January 1, 1753).

For more information, see About Development Storage and Differences Between Development Storage and Windows Azure Storage Services.

URI Parameters

None.

Request Headers

The following table describes required and optional request headers.

Request header	Description
Authorization	Required. Specifies the authentication scheme, account name, and signature. See Authentication Schemes for more information.
Date or x-ms-date	Required. Specifies the UTC time for the request. See for more information. See Authentication Schemes for more information.
x-ms-version	Optional. Specifies the version of the operation to use for this request. See Storage Service Versioning for more information.
Content-Type	Required. The content type of the request body. Currently this header should be set to `application/atom+xml`.
Content-Length	Required. The length of the request body.
If-Match	Required. Specifies the condition for which the update should be performed. To force an unconditional update, set If-Match to the wildcard character (*).

Request Body

The Update Entity operation sends the entity to be updated as an ADO.NET entity set, which is an Atom feed. See Inserting and Updating Entities for more information. For details about the specification for the Atom feed, see the Atom Serialization Rules (ADO.NET Data Services Framework) in the ADO.NET Data Service Specifications.

Sample Request

This example shows a sample request URI, the associated request headers, and the request body.

Request URI:
http://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey1')

Request Headers:
x-ms-version: 2009-04-14
Accept: application/atom+xml,application/xml
Accept-Charset: UTF-8
Content-Type: application/atom+xml
If-Match: *
x-ms-date: Wed, 18 Mar 2009 18:10:24 GMT
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=
Content-Length: ###

Request Body:
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom">
  <title />
  <updated>2008-09-18T23:46:37.168836Z</updated>
  <author>
    <name />
  </author>
<id>http://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')</id>
  <content type="application/xml">
    <m:properties>
      <d:Address>Santa Clara</d:Address>
      <d:Age m:type="Edm.Int32">23</d:Age>
      <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue>
      <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode>
      <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00Z</d:CustomerSince>
      <d:IsActive m:type="Edm.Boolean">false</d:IsActive>
      <d:NumOfOrders m:type="Edm.Int64">255</d:NumOfOrders>
      <d:PartitionKey>mypartitionkey</d:PartitionKey>
      <d:RowKey>myrowkey1</d:RowKey>
      <d:Timestamp m:type="Edm.DateTime">2008-09-18T23:46:36.9557508Z</d:Timestamp>
    </m:properties>
  </content>
</entry>

Response

The response includes an HTTP status code and a set of response headers.

Status Code

A successful operation returns status code 204 (No Content).

For information about status codes, see Status and Error Codes and Table Service Error Codes.

Response Headers

The response includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.

Response header	Description
ETag	The ETag for the entity.
x-ms-request-id	This header uniquely identifies the request that was made and can be used for troubleshooting the request. See Troubleshooting API Operations for more information.

Response Body

None.

Sample Response

Response Status:
HTTP/1.1 204 No Content

Response Headers:
Proxy-Connection: Keep-Alive
Connection: Keep-Alive
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d
Content-Length: 0
Cache-Control: no-cache
Date: Wed, 18 Mar 2009 18:09:54 GMT
ETag: W/"datetime'2009-03-18T18%3A09%3A54.9308145Z'"
Server: Table Service Version 1.0 Microsoft-HTTPAPI/2.0

Authorization

Only the account owner may call this operation.

Remarks

When updating an entity, you must specify the PartitionKey and RowKey system properties as part of the update operation.

An entity's ETag provides default optimistic concurrency for update operations. The ETag value is opaque and should not be read or relied upon. Before an update operation occurs, the Table service verifies that the entity's current ETag value is identical to the ETag value included with the update request. If the values are identical, the Table service determines that the entity has not been modified since it was retrieved, and the update operation proceeds.

If the entity's ETag differs from that specified with the update request, the update operation fails with status code 412 (Precondition Failed). This error indicates that the entity has been changed on the server since it was retrieved. To resolve this error, retrieve the entity again and reissue the request.

To force an unconditional update operation, set the value of the If-Match header to the wildcard character (*) on the request. Passing this value to the operation will override the default optimistic concurrency and ignore any mismatch in ETag values.

If the If-Match header is missing from the request, the service returns status code 400 (Bad Request). A request malformed in other ways may also return 400; see Table Service Error Codes for more information.

If the request specifies a property with a null value, that property is ignored, the update proceeds, and the existing entity is replaced.

Note:
You can take advantage of this behavior to remove a property from an entity.

To explicitly type a property, specify the appropriate ADO.NET Data Services type by setting the m:type attribute within the property definition in the Atom feed. For more information on typing properties, see Inserting and Updating Entities.

Any application that can authenticate and send an HTTP PUT request can update an entity.

Note that you can also use the .NET Client Library for ADO.NET Data Services to update an entity.

For information on performing batch update operations, see Performing Entity Group Transactions.

Concepts

Merge Entity
Authentication Schemes
Status and Error Codes
Table Service Error Codes