Show:
Module: azure

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.

Constructor

Table
(
  • options
)

Defined in lib/table.js:69

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 the DataServiceVersion 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

authorize
(
  • method
  • path
  • query
  • header
)
Promise
protected

Defined in lib/table.js:312

Construct authorized request options by adding signature or shared-access-signature, return promise for the request options.

Parameters:

  • method String
    • HTTP verb in upper case, e.g. GET.
  • path String
    • Path on table resource for storage account.
  • query Object
    • Query-string parameters.
  • header Object
    • Mapping from header key in lowercase to value.

Returns:

Promise:

A promise for an options object compatible with https.request.

createTable
(
  • name
)
Promise

Defined in lib/table.js:472

Create table with given name.

Parameters:

  • name String
    • Name of table to create.

Returns:

Promise:

A promise that the table was created.

deleteEntity
(
  • table
  • partitionKey
  • rowKey
  • options
)
Promise

Defined in lib/table.js:853

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:

Promise:

A promise that the entity was deleted.

deleteTable
(
  • name
)
Promise

Defined in lib/table.js:495

Delete table with given name

Parameters:

  • name String
    • Name of table to delete.

Returns:

Promise:

A promise that the table was marked for deletion.

filter
(
  • expression
)
String

Defined in lib/table.js:513

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:

String:

A filter string for use with queryEntities.

getEntity
(
  • table
  • partitionKey
  • rowKey
  • options
)
Promise

Defined in lib/table.js:615

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:

Promise:

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
)
Promise

Defined in lib/table.js:741

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:

Promise:

A promise for the etag of the inserted entity.

queryEntitites
(
  • table
  • options
)
Promise

Defined in lib/table.js:660

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:

Promise:

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
)
Promise

Defined in lib/table.js:433

Query for tables on the storage account.

Parameters:

  • options Object
    • options on the following form:
    {
      nextTableName:      '...'  // nextTableName, if paging
    }
    

Returns:

Promise:

A promise for an object on the form:

{
 tables:         ['<tableName>', ...],
 nextTableName:  '...',      // nextTableName if paging is necessary
}
request
(
  • method
  • path
  • query
  • header
  • json
)
Promise
private

Defined in lib/table.js:329

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.
  • 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:

Promise:

A promise for the HTTP response object with a payload property carrying the payload as string.

sas
(
  • table
  • options
)
String

Defined in lib/table.js:211

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:

String:

Shared-Access-Signature on string form.

updateEntity
(
  • table
  • options
)
Promise

Defined in lib/table.js:772

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:

Promise:

A promise for eTag of the modified entity.

Attributes

Operators

final static

Defined in lib/table.js:539

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, and
  • azure.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, and
  • azure.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()), and
  • azure.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'...'))"