Export (0) Print
Expand All

Insert Entity

Updated: February 10, 2014

The Insert Entity operation inserts a new entity into a table.

The Insert Entity request may be constructed as follows. HTTPS is recommended. Replace myaccount with the name of your storage account, and mytable with the name of your table:

 

Method Request URI HTTP Version

POST

https://myaccount.table.core.windows.net/mytable

HTTP/1.1

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

 

Method Request URI HTTP Version

POST

http://127.0.0.1:10002/devstoreaccount1/mytable

HTTP/1.1

The Table service in the storage emulator differs from the Windows® Azure™ Table service in several ways. For more information, see About Development Storage and Differences Between the Storage Emulator and Azure Storage Services.

The following table describes required and optional request headers.

 

Request header Description

Authorization

Required. Specifies the authentication scheme, account name, and signature. For more information, see Authentication for the Azure Storage Services.

Date or x-ms-date

Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authentication for the Azure Storage Services.

x-ms-version

Optional. Specifies the version of the operation to use for this request. For more information, see Versioning for the Azure Storage Services.

Content-Type

Required. Specifies the content type of the payload. Possible values are application/atom+xml and application/json.

For more formation about valid content types, see Payload Format for Table Service Operations.

Content-Length

Required. The length of the request body.

Accept

Optional. Specifies the accepted content-type of the response payload. Possible values are:

  • application/atom+xml

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

For more information, see Payload Format for Table Service Operations.

Prefer

Optional. Specifies whether the response should include the inserted entity in the payload. Possible values are return-no-content and return-content. For more information, see Setting the Prefer Header to Manage Response Echo on Insert Operations.

x-ms-client-request-id

Optional. Provides a client-generated, opaque value with a 1 KB character limit that is recorded in the analytics logs when storage analytics logging is enabled. Using this header is highly recommended for correlating client-side activities with requests received by the server. For more information, see About Storage Analytics Logging and Azure Logging: Using Logs to Track Storage Requests.

The Insert Entity operation sends the entity to be inserted as an OData entity, which is either a JSON or an Atom feed. For more information, see Inserting and Updating Entities.

Here is a sample Atom request body for the Insert Entity 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>2013-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>

Here is a sample JSON request body for Insert Entity operation:

{
   "Address":"Mountain View",
   "Age":23,
   "AmountDue":200.23,
   "CustomerCode@odata.type":"Edm.Guid",
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",
   "CustomerSince@odata.type":"Edm.DateTime",
   "CustomerSince":"2008-07-10T00:00:00",
   "IsActive":true,
   "NumberOfOrders@odata.type":"Edm.Int64",
   "NumberOfOrders":"255",
   "PartitionKey":"mypartitionkey",
   "RowKey":"myrowkey"
}

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

The status code depends on the value of the Prefer header. If the Prefer header is set to return-no-content, then a successful operation returns status code 204 (No Content). If the Prefer header is not specified or if it is set to return-content, then a successful operation returns status code 201 (Created). For more information, see Setting the Prefer Header to Manage Response Echo on Insert Operations.

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

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

x-ms-request-id

This header uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshooting API Operations.

x-ms-version

Indicates the version of the Table service used to execute the request. This header is returned for requests made against version 2009-09-19 and later.

Date

A UTC date/time value generated by the service that indicates the time at which the response was initiated.

Preference-Applied

Indicates whether the Prefer request header was honored. If the response does not include this header, then the Prefer header was not honored. If this header is returned, its value will either be return-content or return-no-content.

For more information, see Setting the Prefer Header to Manage Response Echo on Insert Operations.

Content-Type

Indicates the content type of the payload. The value depends on the value specified for the Accept request header. Possible values are:

  • application/atom+xml

  • application/json;odata=nometadata

  • application/json;odata=minimalmetadata

  • application/json;odata=fullmetadata

For more information about content types, see Payload Format for Table Service Operations.

If the request includes the Prefer header with the value return-no-content, no response body is returned. Otherwise, the response body is an OData entity set.

Here is a sample Atom response body for the Insert Entity operation.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="https://myaccount.table.core.windows.net/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:etag="W/&quot;0x5B168C7B6E589D2&quot;" xmlns="http://www.w3.org/2005/Atom">
  <id>https://myaccount.table.core.windows.net/mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')</id>
  <title type="text"></title>
  <updated>2008-09-18T23:46:19.3857256Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="mytable" href="mytable(PartitionKey='mypartitionkey',RowKey='myrowkey1')" />
  <category term="myaccount.Tables" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <content type="application/xml">
    <m:properties>
      <d:PartitionKey>mypartitionkey</d:PartitionKey>
      <d:RowKey>myrowkey1</d:RowKey>
      <d:Timestamp m:type="Edm.DateTime">2008-09-18T23:46:19.4277424Z</d:Timestamp>
      <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: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>
    </m:properties>
  </content>
</entry>

Here is a sample JSON response for each metadata level:

No metadata:

{
   "PartitionKey":"mypartitionkey",
   "RowKey":"myrowkey",
   "Timestamp":"2013-08-22T01:12:06.2608595Z",
   "Address":"Mountain View",
   "Age":23,
   "AmountDue":200.23,
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",
   "CustomerSince":"2008-07-10T00:00:00",
   "IsActive":true,
   "NumberOfOrders":"255"
}

Minimal metadata:

{
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",
   "PartitionKey":"mypartitionkey",
   "RowKey":"myrowkey",
   "Timestamp":"2013-08-22T01:12:06.2608595Z",
   "Address":"Mountain View",
   "Age":23,
   "AmountDue":200.23,
   "CustomerCode@odata.type":"Edm.Guid",
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",
   "CustomerSince@odata.type":"Edm.DateTime",
   "CustomerSince":"2008-07-10T00:00:00",
   "IsActive":true,
   "NumberOfOrders@odata.type":"Edm.Int64",
   "NumberOfOrders":"255"
}

Full metadata:

{
   "odata.metadata":"https://myaccount.table.core.windows.net/Customer/$metadata#Customers/@Element",
   "odata.type":"myaccount.Customers",
   "odata.id":" https://myaccount.table.core.windows.net/Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",
   "odata.etag":"W/\"0x5B168C7B6E589D2\"",
   "odata.editLink":"Customers(PartitionKey='mypartitionkey',RowKey='myrowkey')",
   "PartitionKey":"mypartitionkey",
   "RowKey":"myrowkey",
   "Timestamp@odata.type":"Edm.DateTime",
   "Timestamp":"2013-08-22T01:12:06.2608595Z",
   "Address":"Mountain View",
   "Age":23,
   "AmountDue":200.23,
   "CustomerCode@odata.type":"Edm.Guid",
   "CustomerCode":"c9da6455-213d-42c9-9a79-3e9149a57833",
   "CustomerSince@odata.type":"Edm.DateTime",
   "CustomerSince":"2008-07-10T00:00:00",
   "IsActive":true,
   "NumberOfOrders@odata.type":"Edm.Int64",
   "NumberOfOrders":"255"
}

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

When inserting an entity into a table, 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 OData data 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.

For information about performing batch insert operations, see Performing Entity Group Transactions.

See Also

Show:
© 2014 Microsoft