QueueClient class
A QueueClient represents a URL to an Azure Storage Queue's messages allowing you to manipulate its messages.
- Extends
-
StorageClient
Constructors
| Queue |
Creates an instance of QueueClient. |
| Queue |
Creates an instance of QueueClient. |
| Queue |
Creates an instance of QueueClient. |
Properties
| name | The name of the queue. |
Inherited Properties
| account |
|
| url | URL string value. |
Methods
| clear |
Clear deletes all messages from a queue. See https://docs.microsoft.com/en-us/rest/api/storageservices/clear-messages |
| create(Queue |
Creates a new queue under the specified account. See https://docs.microsoft.com/en-us/rest/api/storageservices/create-queue4 |
| create |
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(Queue |
Deletes the specified queue permanently. See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-queue3 |
| delete |
Deletes the specified queue permanently if it exists. See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-queue3 |
| delete |
deleteMessage permanently removes the specified message from its queue. See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-message2 |
| exists(Queue |
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. |
| generate |
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 |
| get |
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 |
| get |
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 |
| peek |
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 |
| receive |
receiveMessages retrieves one or more messages from the front of the queue. See https://docs.microsoft.com/en-us/rest/api/storageservices/get-messages |
| send |
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 |
| set |
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 |
| set |
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 |
| update |
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 nameProperty Value
string
Inherited Property Details
accountName
accountName: stringProperty Value
string
Inherited From StorageClient.accountName
url
URL string value.
url: stringProperty 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>
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): stringParameters
- 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
- 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.