Azure Storage Tables REST API Reference

Introduction

The Azure Storage Tables REST API allows you to programmatically interact with Azure Table storage. Table storage is a NoSQL key-attribute-value store that can be found in Azure Storage. It is ideal for storing flexible datasets for web applications. You can store and query a large amount of data, and access it from anywhere in the world over HTTP or HTTPS.

This documentation provides details on the various operations you can perform using the REST API, including managing tables and entities.

Table Operations

Create Table

Creates a new table in the storage account.

POST /{accountName}/Tables

Request Headers

Header Description Required
Authorization Specifies the authentication credentials. Yes
Content-Type application/json;odata=fullmetadata Yes
DataServiceVersion 3.0;NetFx No
MaxDataServiceVersion 3.0;NetFx No

Request Body

{
  "TableName": "MyNewTable"
}

Responses

201 Created 400 Bad Request 403 Forbidden 409 Conflict 500 Internal Server Error

List Tables

Retrieves a collection of tables associated with the storage account.

GET /{accountName}/Tables

Query Parameters

Parameter Type Description Optional
$filter String Filters the results. For example, TableName eq 'MyTable'. Yes
$top Integer Specifies the maximum number of tables to return. Yes

Responses

200 OK 400 Bad Request 403 Forbidden 500 Internal Server Error

Delete Table

Deletes a table and all of its data from the storage account.

DELETE /{accountName}/Tables('TableName')

Query Parameters

Parameter Type Description Required
TableName String The name of the table to delete. Must be URL encoded. Yes

Responses

204 No Content 400 Bad Request 403 Forbidden 404 Not Found 500 Internal Server Error

Entity Operations

Insert Entity

Inserts a new entity into a specified table.

POST /{accountName}/TableName()

Request Headers

Header Description Required
Authorization Specifies the authentication credentials. Yes
Content-Type application/json;odata=fullmetadata Yes
DataServiceVersion 3.0;NetFx No
MaxDataServiceVersion 3.0;NetFx No

Request Body

The entity must contain a PartitionKey and RowKey. Other properties are custom attributes.

{
  "PartitionKey": "user1",
  "RowKey": "user1-profile",
  "Email": "user1@example.com",
  "DisplayName": "User One",
  "LastLogin": "2023-10-27T10:00:00Z"
}

Responses

201 Created 400 Bad Request 403 Forbidden 409 Conflict 500 Internal Server Error

Query Entities

Retrieves entities from a specified table.

GET /{accountName}/TableName()

Query Parameters

Parameter Type Description Optional
$filter String Filters the results. For example, PartitionKey eq 'user1' or DisplayName ne 'Admin'. Yes
$select String Specifies which properties to return. For example, Email,DisplayName. Yes
$top Integer Specifies the maximum number of entities to return. Yes
PartitionKey String Retrieves entities for a specific partition. Yes
RowKey String Retrieves a specific entity by its PartitionKey and RowKey. Yes

Responses

200 OK 400 Bad Request 403 Forbidden 404 Not Found 500 Internal Server Error

Update Entity

Updates an existing entity. Use MERGE to update specific properties or REPLACE to replace the entire entity.

MERGE or PUT /{accountName}/TableName(PartitionKey='pk',RowKey='rk')

Request Headers

Header Description Required
Authorization Specifies the authentication credentials. Yes
Content-Type application/json;odata=fullmetadata Yes
If-Match The ETag of the entity to update. Use '*' to update if the entity exists. Yes
DataServiceVersion 3.0;NetFx No
MaxDataServiceVersion 3.0;NetFx No

Request Body

For MERGE, provide only the properties to update. For REPLACE (PUT), provide all properties.

{
  "DisplayName": "User One Updated",
  "LastLogin": "2023-10-27T11:30:00Z"
}

Responses

204 No Content 400 Bad Request 403 Forbidden 404 Not Found 412 Precondition Failed 500 Internal Server Error

Delete Entity

Deletes an entity from a specified table.

DELETE /{accountName}/TableName(PartitionKey='pk',RowKey='rk')

Request Headers

Header Description Required
Authorization Specifies the authentication credentials. Yes
If-Match The ETag of the entity to delete. Use '*' to delete if the entity exists. Yes
DataServiceVersion 3.0;NetFx No
MaxDataServiceVersion 3.0;NetFx No

Responses

204 No Content 400 Bad Request 403 Forbidden 404 Not Found 412 Precondition Failed 500 Internal Server Error

Batch Operations

Batch operations allow you to combine multiple requests into a single HTTP request to improve performance and reduce network overhead.

Important: Batch operations are transactional only for operations within the same table and for specific operations like inserts, updates, and deletes. Table creation and deletion are not supported in batch operations.

POST /$batch

Request Headers

Header Description Required
Authorization Specifies the authentication credentials. Yes
Content-Type multipart/mixed; boundary=batch_boundary Yes
Accept multipart/mixed Yes

Request Body

The body consists of multiple parts, each representing an individual operation. A boundary string separates each part.

--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /{accountName}/MyTable() HTTP/1.1
Content-Type: application/json;odata=fullmetadata
Accept: application/json

{
  "PartitionKey": "batchUser",
  "RowKey": "batchEntity1",
  "Value": 10
}

--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /{accountName}/MyTable() HTTP/1.1
Content-Type: application/json;odata=fullmetadata
Accept: application/json

{
  "PartitionKey": "batchUser",
  "RowKey": "batchEntity2",
  "Value": 20
}

--batch_boundary--

Responses

The response will also be a multipart/mixed response, with each part corresponding to the result of an individual operation in the batch.

202 Accepted 400 Bad Request 403 Forbidden 500 Internal Server Error