fast-azure-storage

  • API Docs for Version: 3.1.5

    • Show:

    Queue

    Module: azure

    Queue client class for interacting with Azure Queue Storage.

    Table of Contents

    Constructor

    Queue
    (
    • options
    )

    Defined in lib/queue.js:50

    Parameters:

    • options Object
      • options on the form:
      {
  // Value for the x-ms-version header fixing the API version
  version:              SERVICE_VERSION,

  // 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,

  // HTTP Agent to use (defaults to a global azure.Agent instance)
  agent:                azure.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/queue.js:252

    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 queue 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.

    clearMessages
    (
    • queue
    )
    Promise

    Defined in lib/queue.js:695

    Clear all messages from queue, note this may timeout if there is a lot of messages in the queue, in this case you'll get a error with the code: OperationTimedOut, and you should retry until the operation is successful. See Azure Queue Storage REST API documentation for details.

    Parameters:

    • queue String
      • Name of queue to clear all messages from.

    Returns:

    Promise:

    A promise that messages have been cleared.

    createQueue
    (
    • queue
    • metadata
    )
    Promise

    Defined in lib/queue.js:399

    Create queue with given name, returns promise that resolves to true, if the queue didn't already exist. Do not rely on this behavior unless you disable the retry logic. Note, if queue exists with different meta-data an error will be thrown.

    Parameters:

    • queue String
      • Name of queue to create.
    • metadata Object
      • Mapping from metadata keys to values.

    Returns:

    Promise:

    A promise that queue has been created.

    deleteMessage
    (
    • queue
    • messageId
    • popReceipt
    )
    Promise

    Defined in lib/queue.js:665

    Delete a message from queue using messageId and popReceipt

    Parameters:

    • queue String
      • Name of queue to delete message from
    • messageId String
      • Message identifier for message to delete, this identifier is given when you call getMessages.
    • popReceipt String
      • Opaque token popReceipt that was given by getMessages when you received the message.

    Returns:

    Promise:

    A promise that the message has been deleted.

    deleteQueue
    (
    • queue
    )
    Promise

    Defined in lib/queue.js:434

    Delete queue, return promise queue is deleted. Note, Azure may take a while to garbage collect the queue, see documentation for relevant details, if you plan to recreate the queue again.

    Parameters:

    • queue String
      • Name of queue to delete.

    Returns:

    Promise:

    A promise that the queue has been marked for deletion.

    getMessages
    (
    • queue
    • options
    )
    Promise

    Defined in lib/queue.js:613

    Get messages from queue, returns up to options.numberOfMessages of messages, note, that Azure Queue Storage only allows up to 32 messages per request. See, deleteMessage for how to delete messages once you have processed them.

    Note, Azure may return zero messages giving you an empty array. This is not necessarily proof the that the queue is empty. See REST documentation for consistency levels.

    Parameters:

    • queue String
      • Name of queue to get messages from.
    • options Object
      • options on the following form:
      {
  numberOfMessages:       1,   // Max number of messages to claim (max 32)
  visibilityTimeout:      30   // Seconds to messages becomes visible again
}

    Returns:

    Promise:

    A promise for an array of messages on the following form:

    [
  {
    messageId:        '...',      // Message id as string
    insertionTime:    new Date(), // Insertion time as Date object
    expirationTime:   new Date(), // Expiration time as Date object
    dequeueCount:     1,          // Message dequeue count
    messageText:      '...',      // Message text (however, you encoded it)
    popReceipt:       '...',      // Opaque string for deleting the message
    timeNextVisible:  new Date()  // Next time visible as Date object
  },
  ...
]
    getMetadata
    (
    • queue
    )
    Promise

    Defined in lib/queue.js:451

    Get meta-data for given queue. This includes approximate message count, note that the approximate message is an upper-bound on the number of messages in the queue.

    Warning, this is a HEAD request, so if the queue is missing you get an error with err.statusCode = 404, but err.code property will be ErrorWithoutCode. The same goes for all other error codes.

    Parameters:

    • queue String
      • Name of queue to get meta-data from.

    Returns:

    Promise:

    A promise for an object on the form:

    {
  messageCount:   50,         // Upper-bound on message count
  metadata: {                 // Mapping from meta-data keys to values
    '<key>':      '<value>',  // Meta-data key/value pair
    ...
  }
}
    listQueues
    (
    • options
    )
    Promise

    Defined in lib/queue.js:347

    List queues under the storage account.

    Parameters:

    • options Object
      • options on the following form:
      {
  prefix:          '',     // Prefix of queues to list
  marker:          '',     // Marker to list queues from
  maxResults:      5000,   // Max number of results
  metadata:        false   // Whether or not to include metadata
}

    Returns:

    Promise:

    A promise for an object on the form:

    {
  queues: [
    {
      name:       '...',      // Name of queue
      metadata:   {}          // Meta-data dictionary if requested
    }
  ],
  prefix:         '...',      // prefix given in options (if given)
  marker:         '...',      // marker given in options (if given)
  maxResults:     5000,       // maxResults given in options (if given)
  nextMarker:     '...'       // Next marker if not at end of list
}
    peekMessages
    (
    • queue
    • options
    )
    Promise

    Defined in lib/queue.js:569

    Peek messages from queue, returns up to options.numberOfMessages, note, that Azure Queue Storage only allows up to 32 messages at once.

    Note, Azure may return zero messages giving you an empty array. This is not necessarily proof the that the queue is empty. See REST documentation for consistency levels.

    Parameters:

    • queue String
      • Name of queue to peek messages from.
    • options Object
      • options on the following form:
      {
  numberOfMessages:       1    // Max number of messages to peek
}

    Returns:

    Promise:

    A promise for an array of messages on the following form:

    [
  {
    messageId:        '...',      // Message id as string
    insertionTime:    new Date(), // Insertion time as Date object
    expirationTime:   new Date(), // Expiration time as Date object
    dequeueCount:     1,          // Message dequeue count
    messageText:      '...'       // Message text (however, you encoded it)
  },
  ...
]
    putMessage
    (
    • queue
    • text
    • options
    )
    Promise

    Defined in lib/queue.js:524

    Put a message with XML-safe text into queue with TTL and visibility- timeout, as given in options.

    Notice that the text must be XML-safe, for JSON it's useful to base64 encode the message. This is what many other libraries does, so make sense for interoperability. Encoding this way is trivial in node.js:

    var text = new Buffer(JSON.stringify(jsonMessage)).toString('base64');

    Parameters:

    • queue String
      • Name of queue to put message into.
    • text String
      • XML-safe string to send.
    • options Object
      • options on the following form:
      {
  visibilityTimeout:    7 * 24 * 60 * 60, // Visibility timeout in seconds
  messageTTL:           7 * 24 * 60 * 60  // Message Time-To-Live in seconds
}

    Returns:

    Promise:

    A promise that the messages was inserted in the queue.

    request
    (
    • method
    • path
    • query
    • header
    • data
    )
    Promise
    private

    Defined in lib/queue.js:269

    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 data 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 queue resource for storage account.
    • query Object
      • Query-string parameters.
    • header Object
      • Mapping from header key in lowercase to value.
    • data String
      • String data to send as UTF-8 payload.

    Returns:

    Promise:

    A promise for HTTPS response with payload property as string containing the response payload.

    sas
    (
    • queue
    • options
    )
    String

    Defined in lib/queue.js:174

    Generate a SAS string on the form 'key1=val1&key2=val2&...'.

    Parameters:

    • queue String
      • Name of queue 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 meta-data and peek messages
    add:           false,      // Add new messages
    update:        false,      // Update messages (after get messages)
    process:       false       // Process messages (get and delete messages)
  },
  accessPolicy:    '...'       // Reference to stored access policy
}

    Returns:

    String:

    Shared-Access-Signature on string form.

    setMetadata
    (
    • queue
    • metadata
    )
    Promise

    Defined in lib/queue.js:491

    Set meta-data for given queue, note that this overwrites all existing meta-data key/value pairs.

    Parameters:

    • queue String
      • Name of queue to set meta-data on.
    • metadata Object
      • Mapping from meta-data keys to values.

    Returns:

    Promise:

    A promise that the meta-data was set.

    updateMessage
    (
    • queue
    • text
    • messageId
    • popReceipt
    • options
    )
    Promise

    Defined in lib/queue.js:716

    Update a message from queue with XML-safe text and visibility-timeout, as given in options.

    Notice that the text must be XML-safe, for JSON it's useful to base64 encode the message. This is what many other libraries does, so make sense for interoperability. Encoding this way is trivial in node.js:

    var text = new Buffer(JSON.stringify(jsonMessage)).toString('base64');

    Parameters:

    • queue String
      • Name of queue in which you wish to update a message.
    • text String
      • XML-safe UTF-8 text to set on the message.
    • messageId String
      • MessageId as received from getMessages.
    • popReceipt String
      • Opaque token as given by getMessages.
    • options Object
      • Options on the following form:
      {
  visibilityTimeout:    7 * 24 * 60 * 60, // Visibility timeout in seconds
}

    Returns:

    Promise:

    A promise that the message has been updated.