Microsoft Azure Table API
Go Up to Azure and Cloud Computing with DataSnap
The Microsoft Azure Table API is located in the DSAzure unit, in the TAzureTableService class. For an example of the API being used, you can look at the implementation section of the DSAzureTable and DSAzureTableDialog units. This is the visual component that uses the API.
Contents
The available functions include: creating a table, deleting a table, getting the available tables, getting the rows (entities) of a table, adding a row to a table, and deleting rows of a table. It is important to note that the Rows do not conform to any schema, and each row can have a different set of Columns (properties.) It is also important to note that all rows will have at least two columns, which together form a unique key for that row: PartitionKey and RowKey. All rows will also have a Timestamp but this isn't meant to be exposed to or modified by any user.
The following instructions will assume you already have an instance created of TAzureTableService. In any code snippets, this instance will be referred to as FTableService. It is also assumed that you have an XML parser at hand and that it is already configured appropriately for use. The API in some cases returns an XML, which you will need to know how to parse.
Getting a list of Tables
To get a list of the available tables, call:
xml := FTableService.QueryTables();
This will return an XML string that will look like this:
<feed ...>
...
<entry>
<id>http://myaccount.tables.core.windows.net/Tables('mytable')</id>
...
<content type="application/xml">
<m:properties>
<d:TableName>mytable</d:TableName>
</m:properties>
</content>
</entry>
</feed>
For a full example of the returned XML and the other info returned, view the MSDN link provided below.
The XML will contain entries, where each entry is a table. The table will have an ID and a list of properties that will include the table's name.
Creating a Table
To create a table, simply call:
Success := FTableService.CreateTable('tablename');
CreateTable returns True if successful, False otherwise. The name you choose for a table must follow these naming conventions:
- Must be lowercase
- Must only contain alphanumeric characters
- Must not start with a numeric character
- Must be from 3 through 63 characters in length
Deleting a Table
To delete a table, use the following code:
Success := FTableService.DeleteTable(FTableName);
Note that the delete on the server may take some time. Even though the table appears to be gone, if you attempt to create a new table with the same name of the deleted table, the creation may fail. If this happens, choose a new name or wait a while and try again.
Listing the Rows of a Table
To get the Rows (entities) of a table, do the following:
xml := FTableService.QueryEntities(FTableName, BuildFilterString);
The XML returned will look like this:
<feed ...>
...
<entry ...>
<id>http://myaccount.tables.core.windows.net/Customers(PartitionKey='SomePKey',RowKey='SomeRKey')</id>
...
<content type="application/xml">
<m:properties>
<d:PartitionKey>SomePKey</d:PartitionKey>
<d:RowKey>SomeRKey</d:RowKey>
<d:Timestamp m:type="Edm.DateTime">2008-10-01T15:26:04.6812774Z</d:Timestamp>
<d:Address>221 Avenue Road, Hollywood CA 90027</d:Address>
<d:SomeNumber m:type="Edm.Int32">27</d:SomeNumber>
</m:properties>
</content>
</entry>
</feed>
To see a full example of the returned XML and all the information it contains, go to the MSDN reference link below.
Each row will be represented as an entry in the XML, and will have its own unique ID. Inside the content node there will be properties that represent the table columns. Each column has a name (the tag) and a value, but may also have a type. This type is one of the supported data types (see the MSDN document referenced below for supported data types.)
Adding a Row to a Table
To create a Row on an existing table, you will need to first create a TJSONObject (using the DBXJSON unit) object that represents the row, with all of its columns (except timestamp). If you use a JSON notation, the object would look something like one of these:
{"RowKey":"row1","PartitionKey":"Imported","AnyKeyName":"Hello World!"}
{"RowKey":"row2","PartitionKey":"Imported","OtherValue":["true","Edm.Boolean"]}
The object must contain a RowKey and PartitionKey, and then any other column/value pairs you want. If you don't specify a data type for the column, String will be assumed. To specify a data type for the value of the column, set it as a TJSONArray, where the first item of the array is the string representation of the column (cell) value, and the second item in the array is the data type for the column. Note that you can't change the value of PartitionKey or RowKey once you created the row.
Once you have the TJSONObject created, call this code (where RowObj is the TJSONObject instance you have created):
xml := FTableService.InsertEntity('tablename', RowObj);
This will return the XML representation of the row you've just added, and will be in the same format as when you query for all the table rows, except the top-level element will be the entry, since the XML will only be representing that one row.
Modifying an Existing Row
If you want to modify an existing row, you create the TJSONObject the same as you would create a new row, but populate the RowKey and PartitionKey appropriately. Instead of calling InsertEntry though, you call UpdateEntry (with the same parameters). This will return True or False, depending on whether the update was successful or not. An update would fail, for example, if a data type selected for a column wasn't valid for the value stored in the column.
Deleting a Row
To delete a row from an existing table, call:
Success := FTableService.DeleteEntity('tablename', PartitionKey, RowKey);
You will need to know only the partition key and row key of the row you want to delete, and the name of the table the row is in. True will be returned provided that the deletion was successful.