Inserting and Updating Entities
Updated: September 13, 2011
To insert or update an entity, you include with the request an XML payload that specifies the properties and data for the entity. The XML payload is in the form of an Atom feed. The Atom feed conforms to the Atom Publishing Protocol specification.
The Insert Entity (REST API) operation inserts a new entity with a unique primary key, formed from the combination of the PartitionKey and the RowKey. The Update Entity (REST API) operation replaces an existing entity with the same PartitionKey and RowKey. The Merge Entity (REST API) operation updates the properties of an existing entity, but does not replace the entity. The Insert Or Merge Entity (REST API) operation creates a new entity with a unique primary key or updates the properties of an existing entity, but does not replace the entity. The Insert Or Replace Entity (REST API) operation creates a new entity with a unique primary key or replaces an existing entity.
Constructing the Atom Feed
The Atom feed for an insert or update operation defines the entity's properties by specifying their names and data types, and sets the values for those properties.
The content element contains the entity's property definitions, which are specified within the m:properties element. The property's type is specified by the m:type attribute.
Here is an example of an Atom feed for an Insert Entity (REST API) operation:
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <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:19.3857256Z<updated/> <author> <name /> </author> <id /> <content type="application/xml"> <m:properties> <d:Address>Mountain View</d:Address> <d:Age m:type="Edm.Int32">23</d:Age> <d:AmountDue m:type="Edm.Double">200.23</d:AmountDue> <d:BinaryData m:type="Edm.Binary" m:null="true" /> <d:CustomerCode m:type="Edm.Guid">c9da6455-213d-42c9-9a79-3e9149a57833</d:CustomerCode> <d:CustomerSince m:type="Edm.DateTime">2008-07-10T00:00:00</d:CustomerSince> <d:IsActive m:type="Edm.Boolean">true</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">0001-01-01T00:00:00</d:Timestamp> </m:properties> </content> </entry>
Property Data Types
Property data types are defined by the WCF Data Services specification. Not all data types defined by the specification are supported by the Table service. For information about the supported data types and how they map to common language runtime (CLR) types, see Understanding the Table Service Data Model.
A property may be specified with or without an explicit data type. If the type is omitted, the property is automatically created as data type Edm.String.
If a property is created with an explicit type, a query that returns the entity includes that type within the Atom feed, so that you can determine the type of an existing property if necessary. Knowing a property's type is important when you are constructing a query that filters on that property. For more information, see Querying Tables and Entities.
Setting the updated Element
Note that the Atom feed for an insert or update operation must include the updated element, which is a timestamp element, as defined in the Atom Syndication Format. The updated element is specified as a string, using the current combined UTC time. Its format is as shown in the following example:
For information about constructing the updated element and other DateTime values, see Formatting DateTime Property Values.