Insert Or Replace Entity (REST API)

The Insert Or Replace Entity request may be constructed as follows. HTTPS is recommended. Replace the following values with your own:

• myaccount with the name of your storage account
  
  
• mytable with the name of your table
  
  
• myPartitionKey and myRowKey1 with the name of the partition key and row key for entity to be updated
  
  

Emulated Storage Service

URI Parameters

Request Headers

Request Body

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

Status Code

Response Headers

Response Body

This operation can be performed by the account owner and by anyone with a shared access signature that has permission to perform this operation.

The following is a sample request and response:

PUT https://myaccount.table.core.windows.net/mytable(PartitionKey='myPartitionKey',RowKey='myRowKey1')

The request is sent with the following headers:

x-ms-version: 2011-08-18
Accept: application/atom+xml,application/xml
Accept-Charset: UTF-8
Content-Type: application/atom+xml
x-ms-date: Tue, 30 Aug 2011 18:10:24 GMT
Authorization: SharedKeyLite myaccount:u0sWZKmjBD1B7LY/CwXWCnHdqK4B1P4z8hKy9SVW49o=
Content-Length: 1135
DataServiceVersion: 1.0;NetFx
MaxDataServiceVersion: 2.0;NetFx

The request is sent with the following XML 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>2011-08-30T18:09:37.168836Z</updated>
  <author>
    <name />
  </author>
<id>https://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">2011-08-30T18:09:37.9557508Z</d:Timestamp>
    </m:properties>
  </content>
</entry>

After the request has been sent, the following response is returned:

HTTP/1.1 204 No Content

Proxy-Connection: Keep-Alive
Connection: Keep-Alive
x-ms-request-id: 2c085f8f-11a4-4e1d-bd49-82c6bd87649d
Content-Length: 0
Cache-Control: no-cache
Date: Tue, 30 Aug 2011 18:12:54 GMT
ETag: W/"datetime'2011-08-30T18%3A12%3A54.9308145Z'"
DataServiceVersion: 1.0;NetFx
MaxDataServiceVersion: 2.0;NetFx
Server: Windows-Azure-Table/1.0 Microsoft-HTTPAPI/2.0

The Insert Or Replace Entity operation does not use the If-Match header and it must be called using the 2011-08-18 version or newer. These attributes distinguish this operation from the Update Entity (REST API) operation.

If the Insert Or Replace Entity operation is used to replace an entity, any properties from the previous entity will be removed if the new entity does not define them. Properties with a null value will also be removed.

When calling the Insert or Replace Entity operation, you must specify values for the PartitionKey and RowKey system properties. Together, these properties form the primary key and must be unique within the table.

Both the PartitionKey and RowKey values must be string values; each key value may be up to 64 KB in size. If you are using an integer value for the key value, you should convert the integer to a fixed-width string, because they are canonically sorted. For example, you should convert the value 1 to 0000001 to ensure proper sorting.

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

Any application that can authenticate and send an HTTP PUT request can insert or replace an entity.

For information about performing batch “upsert” operations, see Performing Entity Group Transactions.

The REST functionality above can be duplicated in .NET by using the WCF Data Services Client Library. The following example demonstrates how to perform an Insert or Replace operation for a given entity:

// Use a DataServiceContext that is not tracking the entity, then attach the entity to the entity set
dataServiceContext.AttachTo("sampleTable", entity);

// Change the state of the entity to "Modified"
dataServiceContext.UpdateObject(entity);

// SaveChangesOptions.ReplaceOnUpdate will generate a PUT request
dataServiceContext.SaveChanges(SaveChangesOptions.ReplaceOnUpdate);

If you use the overridden AttachTo method that accepts an ETag, you must use null for the ETag value. For example: dataServiceContext.AttachTo(“sampleTable”, entity, null);

If your dataServiceContext is already tracking an entity and you want to perform an Insert or Replace operation on that entity, you must detach and reattach the entity. For example:

// Detach the entity
dataServiceContext.Detach(entity);

// Reattach the entity to the entity set
dataServiceContext.AttachTo("sampleTable", entity);

If you don’t detach and then reattach the entity, the Update Entity (REST API) operation would be called instead of the intended Insert Or Replace Entity (REST API) operation.

Concepts