Table
Table client class for interacting with Azure Table Storage.
Subclasses EventEmitter
and emits the error
event on failure to refresh
shared-access-signature, if options.sas
is a function.
Table of Contents
-
Methods
- authorize(methodpathqueryheader)
- createTable(name)
- deleteEntity(tablepartitionKeyrowKeyoptions)
- deleteTable(name)
- filter(expression)
- getEntity(tablepartitionKeyrowKeyoptions)
- insertEntity(tableentity)
- queryEntitites(tableoptions)
- queryTables(options)
- request(methodpathqueryheaderjson)
- sas(tableoptions)
- updateEntity(tableoptions)
- Attributes
Constructor
Table
-
options
Parameters:
-
options
Object- Options on the following form:
{ // Value for the
x-ms-version
header fixing the API version version: '2014-02-14', // OData Service version, must work with API version, refer to azure // documentation. This just specifies theDataServiceVersion
header. dataServiceVersion: '3.0', // Value for the x-ms-client-request-id header identifying the client clientId: 'fast-azure-storage', // Server-side request timeout timeout: 30 * 1000, // Delay between client- and server-side timeout clientTimeoutDelay: 500, // Set meta-data level for responses (use full to get eTag in queryEntities) metadata: 'fullmetadata', // HTTP Agent to use (defaults to a global azure.Agent instance) agent: agent.globalAgent, // Max number of request retries retries: 5, // Multiplier for computation of retry delay: 2 ^ retry * delayFactor delayFactor: 100, // Randomization factor added as: // delay = delay * random([1 - randomizationFactor; 1 + randomizationFactor]) randomizationFactor: 0.25, // Maximum retry delay in ms (defaults to 30 seconds) maxDelay: 30 * 1000, // Error codes for which we should retry transientErrorCodes: TRANSIENT_ERROR_CODES, // Azure storage accountId (required) accountId: undefined, // Azure shared accessKey, required unless options.sas is given accessKey: undefined, // Function that returns SAS string or promise for SAS string, in which // case we will refresh SAS when a request occurs less than // minSASAuthExpiry from signature expiry. This property may also be a // SAS string. sas: undefined, // Minimum SAS expiry before refreshing SAS credentials, if a function for // refreshing SAS credentials is given as options.sas minSASAuthExpiry: 15 * 60 * 1000 }
Methods
createTable
-
name
Create table with given name
.
Parameters:
-
name
String- Name of table to create.
Returns:
A promise that the table was created.
deleteEntity
-
table
-
partitionKey
-
rowKey
-
options
Delete entity identified by partitionKey
and rowKey
from table
.
Options are required for this method and takes form as follows:
{
eTag: '...' || '*' // ETag to delete, or '*' to ignore ETag
}
Note, options.eTag
is '*'
will delete the entity regardless of its ETag.
Parameters:
-
table
String- Name of table to delete entity from.
-
partitionKey
String- Partition key of entity to delete.
-
rowKey
String- Row key of entity to delete.
-
options
Object- Options on the following form:
{ eTag: '...' || '*' // ETag to delete, or '*' to ignore ETag }
Returns:
A promise that the entity was deleted.
deleteTable
-
name
Delete table with given name
Parameters:
-
name
String- Name of table to delete.
Returns:
A promise that the table was marked for deletion.
filter
-
expression
Convert nested array structure to filter string.
See Table.Operators
for details and examples.
Parameters:
-
expression
Array- Array of arrays, keys, operators and formatted constants that forms an expression, where arrays becomes parenthesis:
var op = azure.Table.Operators; var filter = azure.Table.filter([ ['key1', op.Equal, op.string('my-string')], op.And, ['key2', op.LessThan, op.date(new Date())] ]) // "((key1 eq 'my-string') and (key2 le datetime'...'))"
Returns:
A filter string for use with queryEntities
.
getEntity
-
table
-
partitionKey
-
rowKey
-
options
Get entity from table
with given partitionKey
and rowKey
.
Parameters:
-
table
String- Name of table to get entity from.
-
partitionKey
String- Partition key of entity to get.
-
rowKey
String- Row key of entity to get.
-
options
Object- Options on the following form:
{ select: ['key1', ...], // List of keys to return (defaults to all) filter: '...' // Filter string for conditional load }
Returns:
A promise for the entity, form of the object depends on the meta-data
level configured and if select
as employed. See Azure documentation for
details.
insertEntity
-
table
-
entity
Insert entity
into table
, the entity
object must be on the format
accepted by azure table storage. See Azure Table Storage documentation for
details. Essentially, data-types will be inferred if ...@odata.type
properties aren't specified. Also note that PartitionKey
and RowKey
properties must be specified.
Parameters:
-
table
String- Name of table insert entity into.
-
entity
Object- Entity object, see Azure Table Storage documentation for details on how to annotate types.
Returns:
A promise for the etag
of the inserted entity.
queryEntitites
-
table
-
options
Query entities from table
.
Parameters:
-
table
String- Name of table to query entities for.
-
options
Object- Options on the following form:
{ // Query options: select: ['key1', ...], // Keys to $select (defaults to all) filter: 'key1 eq true', // $filter string, see Table.filter top: 1000, // Max number of entities to return // Paging options: nextPartitionKey: '...', // nextPartitionKey from previous result nextRowKey: '...' // nextRowKey from previous result }
Returns:
A promise for an object on the form:
{
entities: [
{
// Keys selected from entity and meta-data depending on meta-data level
},
...
],
nextPartitionKey: '...', // Opaque token for paging
nextRowKey: '...' // Opaque token for paging
}
queryTables
-
options
Query for tables on the storage account.
Parameters:
-
options
Objectoptions
on the following form:
{ nextTableName: '...' // nextTableName, if paging }
Returns:
A promise for an object on the form:
{
tables: ['<tableName>', ...],
nextTableName: '...', // nextTableName if paging is necessary
}
request
-
method
-
path
-
query
-
header
-
json
Make a signed request to path
using method
in upper-case and all query
parameters and headers
keys in lower-case. The request will carry json
as payload and will be retried using the configured retry policy.
Parameters:
-
method
String- HTTP verb in upper case, e.g.
GET
.
- HTTP verb in upper case, e.g.
-
path
String- Path on table resource for storage account.
-
query
Object- Query-string parameters.
-
header
Object- Mapping from header key in lowercase to value.
-
json
Object- Optional JSON object to send as payload.
Returns:
A promise for the HTTP response object with a payload
property carrying the payload as string.
sas
-
table
-
options
Generate a SAS string on the form 'key1=val1&key2=val2&...'
.
Parameters:
-
table
String- Name of table that this SAS string applies to.
-
options
Object- Options for the following form:
{ start: new Date(), // Time from which signature is valid expiry: new Date(), // Expiration of signature (required) permissions: { // Set of permissions delegated (required) read: false, // Read entities add: false, // Insert new entities update: false, // Update entities delete: false // Delete entities }, first: { // Start of accessible range (optional) partitionKey: '...', // First accessible partition key (required) rowKey: '...' // First accessible row key (required) }, last: { // End of accessible range (optional) partitionKey: '...', // Last accessible partition key (required) rowKey: '...' // Last accessible row key (required) }, accessPolicy: '...' // Reference to stored access policy }
Returns:
Shared-Access-Signature on string form.
updateEntity
-
table
-
options
Update entity from table
identified by entity.partitionKey
and
entity.rowKey
.
Options are required for this method and takes form as follows:
{
mode: 'replace' || 'merge' // Replace entity or merge entity
eTag: '...' || '*' || null // Update specific entity, any or allow insert
}
If options.mode
is 'replace'
the remote entity will be completely
replaced by the structure given as entity
. If options.mode
is 'merge'
properties from entity
will overwrite existing properties on remote entity.
If options.eTag
is not given (or null
) the remote entity will be
inserted if it does not exist, and otherwise replaced or merged depending
on mode
.
If options.eTag
is the string '*'
the remote entity will be replaced
or merged depending on mode
, but it will not be inserted if it doesn't
exist.
If options.eTag
is a string (other than '*'
) the remote entity will be
replaced or merged depending on mode
, if the ETag of the remote entity
matches the string given in options.eTag
.
Combining mode
and eTag
options this method implements the following
operations:
- Insert or replace (regardless of existence or ETag),
- Replace if exists (regardless of ETag),
- Replace if exists and has given ETag,
- Insert or merge (regardless of existence or ETag),
- Merge if exists (regardless of ETag), and
- Merge if exists and has given ETag.
Parameters:
-
table
String- Name of table to update entity from.
-
options
Object- Options on the following form:
{ mode: 'replace' || 'merge' // Replace entity or merge entity eTag: '...' || '*' || null // Update specific entity, any or allow insert }
Returns:
A promise for eTag
of the modified entity.
Attributes
Operators
final
static
Operators and helpers for constructing $filter strings using Table.filter
.
We have the following comparison operators:
azure.Table.Operators.Equal
,azure.Table.Operators.GreaterThan
,azure.Table.Operators.GreaterThanOrEqual
,azure.Table.Operators.LessThan
,azure.Table.Operators.LessThanOrEqual
, andazure.Table.Operators.NotEqual
.
They should be used in the middle of a triple as follows:
['key1', op.Equal, op.string('my-string')]
.
The boolean operators And
, Not
and Or
should be used to connect
triples made with comparison operators. Note, that each set of array brackets
translates into a parentheses. Boolean operators:
azure.Table.Operators.And
,azure.Table.Operators.Not
, andazure.Table.Operators.Or
.
We also have formatting helpers, string
, number
, bool
, date
and
guid
which takes constant values and encodes them correctly for use in
filter expression. It's strongly recommended that you employ these, as Azure
has some undocumented and semi obscure escaping rules. Constant formatters:
azure.Table.Operators.string("...")
,azure.Table.Operators.number(42.2)
,azure.Table.Operators.bool(true)
,azure.Table.Operators.date(new Date())
, andazure.Table.Operators.guid('...')
.
Complete example:
var op = azure.Table.Operators;
var filter = azure.Table.filter([
['key1', op.Equal, op.string('my-string')],
op.And,
['key2', op.LessThan, op.date(new Date())]
]) // "((key1 eq 'my-string') and (key2 le datetime'...'))"