Share via

QueueServiceClient class

  • Reference
Package:
@azure/storage-queue

A QueueServiceClient represents a URL to the Azure Storage Queue service allowing you to manipulate queues.

Extends

StorageClient

Constructors

QueueServiceClient(string, Pipeline)

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

Creates an instance of QueueServiceClient.

Inherited Properties

accountName
url

URL string value.

Methods

createQueue(string, QueueCreateOptions)

Creates a new queue under the specified account.

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

Deletes the specified queue permanently.

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

Creates an instance of QueueServiceClient.
generateAccountSasUrl(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for QueueServiceClient constructed with a shared key credential.

Generates an account 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/create-account-sas
generateSasStringToSign(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for QueueServiceClient constructed with a shared key credential.

Generates string to sign for an account 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/create-account-sas
getProperties(ServiceGetPropertiesOptions)

Gets the properties of a storage account’s Queue service, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-queue-service-properties
getQueueClient(string)

Creates a QueueClient object.
getStatistics(ServiceGetStatisticsOptions)

Retrieves statistics related to replication for the Queue service. It is only available on the secondary location endpoint when read-access geo-redundant replication is enabled for the storage account.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-queue-service-stats
listQueues(ServiceListQueuesOptions)

Returns an async iterable iterator to list all the queues under the specified account.

.byPage() returns an async iterable iterator to list the queues in pages.

Example using for await syntax:

let i = 1;
for await (const item of queueServiceClient.listQueues()) {
  console.log(`Queue${i}: ${item.name}`);
  i++;
}

Example using iter.next():

let i = 1;
let iterator = queueServiceClient.listQueues();
let item = await iterator.next();
while (!item.done) {
  console.log(`Queue${i}: ${item.value.name}`);
  i++;
  item = await iterator.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const item2 of queueServiceClient.listQueues().byPage({ maxPageSize: 20 })) {
  if (item2.queueItems) {
    for (const queueItem of item2.queueItems) {
      console.log(`Queue${i}: ${queueItem.name}`);
      i++;
    }
  }
}

Example using paging with a marker:

let i = 1;
let iterator = queueServiceClient.listQueues().byPage({ maxPageSize: 2 });
let item = (await iterator.next()).value;

// Prints 2 queue names
if (item.queueItems) {
  for (const queueItem of item.queueItems) {
    console.log(`Queue${i}: ${queueItem.name}`);
    i++;
  }
}
// Gets next marker
let marker = item.continuationToken;

// Passing next marker as continuationToken
iterator = queueServiceClient.listQueues().byPage({ continuationToken: marker, maxPageSize: 10 });
item = (await iterator.next()).value;

// Prints 10 queue names
if (item.queueItems) {
  for (const queueItem of item.queueItems) {
    console.log(`Queue${i}: ${queueItem.name}`);
    i++;
  }
}
setProperties(QueueServiceProperties, ServiceGetPropertiesOptions)

Sets properties for a storage account’s Queue service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings.

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

Constructor Details

QueueServiceClient(string, Pipeline)

Creates an instance of QueueServiceClient.

new QueueServiceClient(url: string, pipeline: Pipeline)

Parameters

url

string

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

pipeline
Pipeline

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

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

Creates an instance of QueueServiceClient.

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

Parameters

url

string

A URL string pointing to Azure Storage queue service, such as "https://myaccount.queue.core.windows.net". You can append a SAS if using AnonymousCredential, such as "https://myaccount.queue.core.windows.net?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.

Example using DefaultAzureCredential from @azure/identity:

const account = "<account>";

const credential = new DefaultAzureCredential();

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  credential
}

Example using an account name/key:

const account = "<account>";

const sharedKeyCredential = new StorageSharedKeyCredential(account, "<account key>");

const queueServiceClient = new QueueServiceClient(
  `https://${account}.queue.core.windows.net`,
  sharedKeyCredential,
  {
    retryOptions: { maxTries: 4 }, // Retry options
    telemetry: { value: "BasicSample/V11.0.0" } // Customized telemetry 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

createQueue(string, QueueCreateOptions)

Creates a new queue under the specified account.

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

function createQueue(queueName: string, options?: QueueCreateOptions): Promise<QueueCreateResponse>

Parameters

queueName

string

name of the queue to create

options
QueueCreateOptions

Options to Queue create operation.

Returns

Promise<QueueCreateResponse>

Response data for the Queue create operation.

deleteQueue(string, QueueDeleteOptions)

Deletes the specified queue permanently.

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

function deleteQueue(queueName: string, options?: QueueDeleteOptions): Promise<QueueDeleteResponse>

Parameters

queueName

string

name of the queue to delete.

options
QueueDeleteOptions

Options to Queue delete operation.

Returns

Promise<QueueDeleteResponse>

Response data for the Queue delete operation.

fromConnectionString(string, StoragePipelineOptions)

Creates an instance of QueueServiceClient.

static function fromConnectionString(connectionString: string, options?: StoragePipelineOptions): QueueServiceClient

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

options
StoragePipelineOptions

Options to configure the HTTP pipeline.

Returns

QueueServiceClient

A new QueueServiceClient object from the given connection string.

generateAccountSasUrl(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for QueueServiceClient constructed with a shared key credential.

Generates an account 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/create-account-sas

function generateAccountSasUrl(expiresOn?: Date, permissions?: AccountSASPermissions, resourceTypes?: string, options?: ServiceGenerateAccountSasUrlOptions): string

Parameters

expiresOn

Date

Optional. The time at which the shared access signature becomes invalid. Default to an hour later if not specified.

permissions
AccountSASPermissions

Specifies the list of permissions to be associated with the SAS.

resourceTypes

string

Specifies the resource types associated with the shared access signature.

options
ServiceGenerateAccountSasUrlOptions

Optional parameters.

Returns

string

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

generateSasStringToSign(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for QueueServiceClient constructed with a shared key credential.

Generates string to sign for an account 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/create-account-sas

function generateSasStringToSign(expiresOn?: Date, permissions?: AccountSASPermissions, resourceTypes?: string, options?: ServiceGenerateAccountSasUrlOptions): string

Parameters

expiresOn

Date

Optional. The time at which the shared access signature becomes invalid. Default to an hour later if not specified.

permissions
AccountSASPermissions

Specifies the list of permissions to be associated with the SAS.

resourceTypes

string

Specifies the resource types associated with the shared access signature.

options
ServiceGenerateAccountSasUrlOptions

Optional parameters.

Returns

string

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

getProperties(ServiceGetPropertiesOptions)

Gets the properties of a storage account’s Queue service, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

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

function getProperties(options?: ServiceGetPropertiesOptions): Promise<ServiceGetPropertiesResponse>

Parameters

options
ServiceGetPropertiesOptions

Options to get properties operation.

Returns

Promise<ServiceGetPropertiesResponse>

Response data including the queue service properties.

getQueueClient(string)

Creates a QueueClient object.

function getQueueClient(queueName: string): QueueClient

Parameters

queueName

string

Returns

QueueClient

a new QueueClient

Example usage:

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

getStatistics(ServiceGetStatisticsOptions)

Retrieves statistics related to replication for the Queue service. It is only available on the secondary location endpoint when read-access geo-redundant replication is enabled for the storage account.

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

function getStatistics(options?: ServiceGetStatisticsOptions): Promise<ServiceGetStatisticsResponse>

Parameters

options
ServiceGetStatisticsOptions

Options to get statistics operation.

Returns

Promise<ServiceGetStatisticsResponse>

Response data for get statistics the operation.

listQueues(ServiceListQueuesOptions)

Returns an async iterable iterator to list all the queues under the specified account.

.byPage() returns an async iterable iterator to list the queues in pages.

Example using for await syntax:

let i = 1;
for await (const item of queueServiceClient.listQueues()) {
  console.log(`Queue${i}: ${item.name}`);
  i++;
}

Example using iter.next():

let i = 1;
let iterator = queueServiceClient.listQueues();
let item = await iterator.next();
while (!item.done) {
  console.log(`Queue${i}: ${item.value.name}`);
  i++;
  item = await iterator.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const item2 of queueServiceClient.listQueues().byPage({ maxPageSize: 20 })) {
  if (item2.queueItems) {
    for (const queueItem of item2.queueItems) {
      console.log(`Queue${i}: ${queueItem.name}`);
      i++;
    }
  }
}

Example using paging with a marker:

let i = 1;
let iterator = queueServiceClient.listQueues().byPage({ maxPageSize: 2 });
let item = (await iterator.next()).value;

// Prints 2 queue names
if (item.queueItems) {
  for (const queueItem of item.queueItems) {
    console.log(`Queue${i}: ${queueItem.name}`);
    i++;
  }
}
// Gets next marker
let marker = item.continuationToken;

// Passing next marker as continuationToken
iterator = queueServiceClient.listQueues().byPage({ continuationToken: marker, maxPageSize: 10 });
item = (await iterator.next()).value;

// Prints 10 queue names
if (item.queueItems) {
  for (const queueItem of item.queueItems) {
    console.log(`Queue${i}: ${queueItem.name}`);
    i++;
  }
}

function listQueues(options?: ServiceListQueuesOptions): PagedAsyncIterableIterator<QueueItem, ServiceListQueuesSegmentResponse, PageSettings>

Parameters

options
ServiceListQueuesOptions

Options to list queues operation.

Returns

PagedAsyncIterableIterator<QueueItem, ServiceListQueuesSegmentResponse, PageSettings>

An asyncIterableIterator that supports paging.

setProperties(QueueServiceProperties, ServiceGetPropertiesOptions)

Sets properties for a storage account’s Queue service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings.

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

function setProperties(properties: QueueServiceProperties, options?: ServiceGetPropertiesOptions): Promise<ServiceSetPropertiesResponse>

Parameters

properties
QueueServiceProperties
options
ServiceGetPropertiesOptions

Options to set properties operation.

Returns

Promise<ServiceSetPropertiesResponse>

Response data for the Set Properties operation.