Share via

QueueClient class

  • Reference
Package:
@azure/storage-queue

A QueueClient represents a URL to an Azure Storage Queue's messages allowing you to manipulate its messages.

Extends

StorageClient

Constructors

QueueClient(string, Pipeline)

Creates an instance of QueueClient.
QueueClient(string, StorageSharedKeyCredential | AnonymousCredential | TokenCredential, StoragePipelineOptions)

Creates an instance of QueueClient.
QueueClient(string, string, StoragePipelineOptions)

Creates an instance of QueueClient.

Properties

name

The name of the queue.

Inherited Properties

accountName
url

URL string value.

Methods

clearMessages(QueueClearMessagesOptions)

Clear deletes all messages from a queue.

See https://docs.microsoft.com/en-us/rest/api/storageservices/clear-messages
create(QueueCreateOptions)

Creates a new queue under the specified account.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-queue4
createIfNotExists(QueueCreateOptions)

Creates a new queue under the specified account if it doesn't already exist. If the queue already exists, it is not changed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-queue4
delete(QueueDeleteOptions)

Deletes the specified queue permanently.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-queue3
deleteIfExists(QueueDeleteOptions)

Deletes the specified queue permanently if it exists.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-queue3
deleteMessage(string, string, QueueDeleteMessageOptions)

deleteMessage permanently removes the specified message from its queue.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-message2
exists(QueueExistsOptions)

Returns true if the specified queue exists; false otherwise.

NOTE: use this function with care since an existing queue might be deleted by other clients or applications. Vice versa new queues might be added by other clients or applications after this function completes.
generateSasStringToSign(QueueGenerateSasUrlOptions)

Only available for QueueClient constructed with a shared key credential.

Generates string to sign for a Service Shared Access Signature (SAS) URI based on the client properties and parameters passed in. The SAS is signed by the shared key credential of the client.

See https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas
generateSasUrl(QueueGenerateSasUrlOptions)

Only available for QueueClient constructed with a shared key credential.

Generates a Service Shared Access Signature (SAS) URI based on the client properties and parameters passed in. The SAS is signed by the shared key credential of the client.

See https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas
getAccessPolicy(QueueGetAccessPolicyOptions)

Gets details about any stored access policies specified on the queue that may be used with Shared Access Signatures.

WARNING: JavaScript Date will potential lost precision when parsing start and expiry string. For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z".

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-queue-acl
getProperties(QueueGetPropertiesOptions)

Gets all user-defined metadata and system properties for the specified queue. Metadata is associated with the queue as name-values pairs.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-queue-metadata

WARNING: The metadata object returned in the response will have its keys in lowercase, even if they originally contained uppercase characters. This differs from the metadata keys returned by the listQueues method of QueueServiceClient using the includeMetadata option, which will retain their original casing.
peekMessages(QueuePeekMessagesOptions)

peekMessages retrieves one or more messages from the front of the queue but does not alter the visibility of the message.

See https://docs.microsoft.com/en-us/rest/api/storageservices/peek-messages
receiveMessages(QueueReceiveMessageOptions)

receiveMessages retrieves one or more messages from the front of the queue.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-messages
sendMessage(string, QueueSendMessageOptions)

sendMessage adds a new message to the back of a queue. The visibility timeout specifies how long the message should be invisible to Dequeue and Peek operations. The message content is up to 64KB in size, and must be in a format that can be included in an XML request with UTF-8 encoding. To include markup in the message, the contents of the message must either be XML-escaped or Base64-encode.

See https://docs.microsoft.com/en-us/rest/api/storageservices/put-message
setAccessPolicy(SignedIdentifier[], QueueSetAccessPolicyOptions)

Sets stored access policies for the queue that may be used with Shared Access Signatures.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-queue-acl
setMetadata(Metadata, QueueSetMetadataOptions)

Sets one or more user-defined name-value pairs for the specified queue.

If no option provided, or no metadata defined in the option parameter, the queue metadata will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-queue-metadata
updateMessage(string, string, string, number, QueueUpdateMessageOptions)

Update changes a message's visibility timeout and contents. The message content is up to 64KB in size, and must be in a format that can be included in an XML request with UTF-8 encoding. To include markup in the message, the contents of the message must either be XML-escaped or Base64-encode.

See https://docs.microsoft.com/en-us/rest/api/storageservices/update-message

Constructor Details

QueueClient(string, Pipeline)

Creates an instance of QueueClient.

new QueueClient(url: string, pipeline: Pipeline)

Parameters

url

string

A URL string pointing to Azure Storage queue, such as "https://myaccount.queue.core.windows.net/myqueue". You can append a SAS if using AnonymousCredential, such as "https://myaccount.queue.core.windows.net/myqueue?sasString".

pipeline
Pipeline

Call newPipeline() to create a default pipeline, or provide a customized pipeline.

QueueClient(string, StorageSharedKeyCredential | AnonymousCredential | TokenCredential, StoragePipelineOptions)

Creates an instance of QueueClient.

new QueueClient(url: string, credential?: StorageSharedKeyCredential | AnonymousCredential | TokenCredential, options?: StoragePipelineOptions)

Parameters

url

string

A URL string pointing to Azure Storage queue, such as "https://myaccount.queue.core.windows.net/myqueue". You can append a SAS if using AnonymousCredential, such as "https://myaccount.queue.core.windows.net/myqueue?sasString".

credential

StorageSharedKeyCredential | AnonymousCredential | TokenCredential

Such as AnonymousCredential, StorageSharedKeyCredential or any credential from the @azure/identity package to authenticate requests to the service. You can also provide an object that implements the TokenCredential interface. If not specified, AnonymousCredential is used.

options
StoragePipelineOptions

Options to configure the HTTP pipeline.

QueueClient(string, string, StoragePipelineOptions)

Creates an instance of QueueClient.

new QueueClient(connectionString: string, queueName: string, options?: StoragePipelineOptions)

Parameters

connectionString

string

Account connection string or a SAS connection string of an Azure storage account. [ Note - Account connection string can only be used in NODE.JS runtime. ] Account connection string example - DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=accountKey;EndpointSuffix=core.windows.net SAS connection string example - BlobEndpoint=https://myaccount.blob.core.windows.net/;QueueEndpoint=https://myaccount.queue.core.windows.net/;FileEndpoint=https://myaccount.file.core.windows.net/;TableEndpoint=https://myaccount.table.core.windows.net/;SharedAccessSignature=sasString

queueName

string

Queue name.

options
StoragePipelineOptions

Options to configure the HTTP pipeline.

Property Details

name

The name of the queue.

string name

Property Value

string

Inherited Property Details

accountName 

accountName: string

Property Value

string

Inherited From StorageClient.accountName

url

URL string value.

url: string

Property Value

string

Inherited From StorageClient.url

Method Details

clearMessages(QueueClearMessagesOptions)

Clear deletes all messages from a queue.

See https://docs.microsoft.com/en-us/rest/api/storageservices/clear-messages

function clearMessages(options?: QueueClearMessagesOptions): Promise<MessagesClearResponse>

Parameters

options
QueueClearMessagesOptions

Options to clear messages operation.

Returns

Promise<MessagesClearResponse>

Response data for the clear messages operation.

create(QueueCreateOptions)

Creates a new queue under the specified account.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-queue4

function create(options?: QueueCreateOptions): Promise<QueueCreateResponse>

Parameters

options
QueueCreateOptions

Options to Queue create operation.

Returns

Promise<QueueCreateResponse>

Response data for the Queue create operation.

Example usage:

const queueClient = queueServiceClient.getQueueClient("<new queue name>");
const createQueueResponse = await queueClient.create();

createIfNotExists(QueueCreateOptions)

Creates a new queue under the specified account if it doesn't already exist. If the queue already exists, it is not changed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-queue4

function createIfNotExists(options?: QueueCreateOptions): Promise<QueueCreateIfNotExistsResponse>

Parameters

options
QueueCreateOptions

Returns

Promise<QueueCreateIfNotExistsResponse>

delete(QueueDeleteOptions)

Deletes the specified queue permanently.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-queue3

function delete(options?: QueueDeleteOptions): Promise<QueueDeleteResponse>

Parameters

options
QueueDeleteOptions

Options to Queue delete operation.

Returns

Promise<QueueDeleteResponse>

Response data for the Queue delete operation.

Example usage:

const deleteQueueResponse = await queueClient.delete();
console.log(
  "Delete queue successfully, service assigned request Id:", deleteQueueResponse.requestId
);

deleteIfExists(QueueDeleteOptions)

Deletes the specified queue permanently if it exists.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-queue3

function deleteIfExists(options?: QueueDeleteOptions): Promise<QueueDeleteIfExistsResponse>

Parameters

options
QueueDeleteOptions

Returns

Promise<QueueDeleteIfExistsResponse>

deleteMessage(string, string, QueueDeleteMessageOptions)

deleteMessage permanently removes the specified message from its queue.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-message2

function deleteMessage(messageId: string, popReceipt: string, options?: QueueDeleteMessageOptions): Promise<MessageIdDeleteResponse>

Parameters

messageId

string

Id of the message.

popReceipt

string

A valid pop receipt value returned from an earlier call to the receive messages or update message operation.

options
QueueDeleteMessageOptions

Options to delete message operation.

Returns

Promise<MessageIdDeleteResponse>

Response data for the delete message operation.

exists(QueueExistsOptions)

Returns true if the specified queue exists; false otherwise.

NOTE: use this function with care since an existing queue might be deleted by other clients or applications. Vice versa new queues might be added by other clients or applications after this function completes.

function exists(options?: QueueExistsOptions): Promise<boolean>

Parameters

options
QueueExistsOptions

options to Exists operation.

Returns

Promise<boolean>

generateSasStringToSign(QueueGenerateSasUrlOptions)

Only available for QueueClient constructed with a shared key credential.

Generates string to sign for a Service Shared Access Signature (SAS) URI based on the client properties and parameters passed in. The SAS is signed by the shared key credential of the client.

See https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas

function generateSasStringToSign(options: QueueGenerateSasUrlOptions): string

Parameters

options
QueueGenerateSasUrlOptions

Optional parameters.

Returns

string

The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token.

generateSasUrl(QueueGenerateSasUrlOptions)

Only available for QueueClient constructed with a shared key credential.

Generates a Service Shared Access Signature (SAS) URI based on the client properties and parameters passed in. The SAS is signed by the shared key credential of the client.

See https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas

function generateSasUrl(options: QueueGenerateSasUrlOptions): string

Parameters

options
QueueGenerateSasUrlOptions

Optional parameters.

Returns

string

The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token.

getAccessPolicy(QueueGetAccessPolicyOptions)

Gets details about any stored access policies specified on the queue that may be used with Shared Access Signatures.

WARNING: JavaScript Date will potential lost precision when parsing start and expiry string. For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z".

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-queue-acl

function getAccessPolicy(options?: QueueGetAccessPolicyOptions): Promise<QueueGetAccessPolicyResponse>

Parameters

options
QueueGetAccessPolicyOptions

Options to Queue get access policy operation.

Returns

Promise<QueueGetAccessPolicyResponse>

Response data for the Queue get access policy operation.

getProperties(QueueGetPropertiesOptions)

Gets all user-defined metadata and system properties for the specified queue. Metadata is associated with the queue as name-values pairs.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-queue-metadata

WARNING: The metadata object returned in the response will have its keys in lowercase, even if they originally contained uppercase characters. This differs from the metadata keys returned by the listQueues method of QueueServiceClient using the includeMetadata option, which will retain their original casing.

function getProperties(options?: QueueGetPropertiesOptions): Promise<QueueGetPropertiesResponse>

Parameters

options
QueueGetPropertiesOptions

Options to Queue get properties operation.

Returns

Promise<QueueGetPropertiesResponse>

Response data for the Queue get properties operation.

peekMessages(QueuePeekMessagesOptions)

peekMessages retrieves one or more messages from the front of the queue but does not alter the visibility of the message.

See https://docs.microsoft.com/en-us/rest/api/storageservices/peek-messages

function peekMessages(options?: QueuePeekMessagesOptions): Promise<QueuePeekMessagesResponse>

Parameters

options
QueuePeekMessagesOptions

Options to peek messages operation.

Returns

Promise<QueuePeekMessagesResponse>

Response data for the peek messages operation.

Example usage:

const peekMessagesResponse = await queueClient.peekMessages();
console.log("The peeked message is:", peekMessagesResponse.peekedMessageItems[0].messageText);

receiveMessages(QueueReceiveMessageOptions)

receiveMessages retrieves one or more messages from the front of the queue.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-messages

function receiveMessages(options?: QueueReceiveMessageOptions): Promise<QueueReceiveMessageResponse>

Parameters

options
QueueReceiveMessageOptions

Options to receive messages operation.

Returns

Promise<QueueReceiveMessageResponse>

Response data for the receive messages operation.

Example usage:

const response = await queueClient.receiveMessages();
if (response.receivedMessageItems.length == 1) {
  const receivedMessageItem = response.receivedMessageItems[0];
  console.log("Processing & deleting message with content:", receivedMessageItem.messageText);
  const deleteMessageResponse = await queueClient.deleteMessage(
    receivedMessageItem.messageId,
    receivedMessageItem.popReceipt
  );
  console.log(
    "Delete message successfully, service assigned request Id:",
    deleteMessageResponse.requestId
  );
}

sendMessage(string, QueueSendMessageOptions)

sendMessage adds a new message to the back of a queue. The visibility timeout specifies how long the message should be invisible to Dequeue and Peek operations. The message content is up to 64KB in size, and must be in a format that can be included in an XML request with UTF-8 encoding. To include markup in the message, the contents of the message must either be XML-escaped or Base64-encode.

See https://docs.microsoft.com/en-us/rest/api/storageservices/put-message

function sendMessage(messageText: string, options?: QueueSendMessageOptions): Promise<QueueSendMessageResponse>

Parameters

messageText

string

Text of the message to send

options
QueueSendMessageOptions

Options to send messages operation.

Returns

Promise<QueueSendMessageResponse>

Response data for the send messages operation.

Example usage:

const sendMessageResponse = await queueClient.sendMessage("Hello World!");
console.log(
  "Sent message successfully, service assigned message Id:", sendMessageResponse.messageId,
  "service assigned request Id:", sendMessageResponse.requestId
);

setAccessPolicy(SignedIdentifier[], QueueSetAccessPolicyOptions)

Sets stored access policies for the queue that may be used with Shared Access Signatures.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-queue-acl

function setAccessPolicy(queueAcl?: SignedIdentifier[], options?: QueueSetAccessPolicyOptions): Promise<QueueSetAccessPolicyResponse>

Parameters

queueAcl

SignedIdentifier[]

options
QueueSetAccessPolicyOptions

Options to Queue set access policy operation.

Returns

Promise<QueueSetAccessPolicyResponse>

Response data for the Queue set access policy operation.

setMetadata(Metadata, QueueSetMetadataOptions)

Sets one or more user-defined name-value pairs for the specified queue.

If no option provided, or no metadata defined in the option parameter, the queue metadata will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-queue-metadata

function setMetadata(metadata?: Metadata, options?: QueueSetMetadataOptions): Promise<QueueSetMetadataResponse>

Parameters

metadata
Metadata

If no metadata provided, all existing metadata will be removed.

options
QueueSetMetadataOptions

Options to Queue set metadata operation.

Returns

Promise<QueueSetMetadataResponse>

Response data for the Queue set metadata operation.

updateMessage(string, string, string, number, QueueUpdateMessageOptions)

Update changes a message's visibility timeout and contents. The message content is up to 64KB in size, and must be in a format that can be included in an XML request with UTF-8 encoding. To include markup in the message, the contents of the message must either be XML-escaped or Base64-encode.

See https://docs.microsoft.com/en-us/rest/api/storageservices/update-message

function updateMessage(messageId: string, popReceipt: string, message?: string, visibilityTimeout?: number, options?: QueueUpdateMessageOptions): Promise<MessageIdUpdateResponse>

Parameters

messageId

string

Id of the message

popReceipt

string

A valid pop receipt value returned from an earlier call to the receive messages or update message operation.

message

string

Message to update. If this parameter is undefined, then the content of the message won't be updated.

visibilityTimeout

number

Specifies the new visibility timeout value, in seconds, relative to server time. The new value must be larger than or equal to 0, and cannot be larger than 7 days. The visibility timeout of a message cannot be set to a value later than the expiry time. A message can be updated until it has been deleted or has expired.

options
QueueUpdateMessageOptions

Options to update message operation.

Returns

Promise<MessageIdUpdateResponse>

Response data for the update message operation.