Categorygithub.com/Azure/azure-sdk-for-go/sdk/storage/azqueue
modulepackage
1.0.0
Repository: https://github.com/azure/azure-sdk-for-go.git
Documentation: pkg.go.dev

# README

Azure Queue Storage SDK for Go

Service Version: 2018-03-28

Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in the world via authenticated calls using HTTP or HTTPS. A single queue message can be up to 64 KiB in size, and a queue can contain millions of messages, up to the total capacity limit of a storage account.

Source code | API reference documentation | REST API documentation

Getting started

Install the package

Install the Azure Queue Storage SDK for Go with go get:

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azqueue

If you're going to authenticate with Azure Active Directory (recommended), install the azidentity module.

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Prerequisites

A supported Go version (the Azure SDK supports the two most recent Go releases).

You need an Azure subscription and a Storage Account to use this package.

To create a new Storage Account, you can use the Azure Portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:

az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS

Authenticate the client

In order to interact with the Azure Queue Storage service, you'll need to create an instance of the azqueue.ServiceClient type. The azidentity module makes it easy to add Azure Active Directory support for authenticating Azure SDK clients with their corresponding Azure services.

// create a credential for authenticating with Azure Active Directory
cred, err := azidentity.NewDefaultAzureCredential(nil)
// TODO: handle err

// create an azqueue.ServiceClient for the specified storage account that uses the above credential
client, err := azqueue.NewServiceClient("https://MYSTORAGEACCOUNT.queue.core.windows.net/", cred, nil)
// TODO: handle err

Learn more about enabling Azure Active Directory for authentication with Azure Storage in our documentation and our samples.

Key concepts

The following components make up the Azure Queue Service:

  • The storage account itself
  • A queue within the storage account, which contains a set of messages
  • A message within a queue, in any format, of up to 64 KiB

The Azure Storage Queues client library for GO allows you to interact with each of these components through the use of a dedicated client object.

Clients

Two different clients are provided to interact with the various components of the Queue Service:

  1. ServiceClient - this client represents interaction with the Azure storage account itself, and allows you to acquire preconfigured client instances to access the queues within. It provides operations to retrieve and configure the account properties as well as list, create, and delete queues within the account. To perform operations on a specific queue, retrieve a client using the NewQueueClient method.
  2. QueueClient - this client represents interaction with a specific queue (which need not exist yet). It provides operations to create, delete, or configure a queue and includes operations to enqueue, dequeue, peek, delete, and update messages within it.

Messages

  • Enqueue - Adds a message to the queue and optionally sets a visibility timeout for the message.
  • Dequeue - Retrieves a message from the queue and makes it invisible to other consumers.
  • Peek - Retrieves a message from the front of the queue, without changing the message visibility.
  • Update - Updates the visibility timeout of a message and/or the message contents.
  • Delete - Deletes a specified message from the queue.
  • Clear - Clears all messages from the queue.

Goroutine safety

We guarantee that all client instance methods are goroutine-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across goroutines.

About Queue metadata

Queue metadata name/value pairs are valid HTTP headers and should adhere to all restrictions governing HTTP headers. Metadata names must be valid HTTP header names, may contain only ASCII characters, and should be treated as case-insensitive. Base64-encode or URL-encode metadata values containing non-ASCII characters.

Additional concepts

Client options | Accessing the response | Handling failures | Logging

Examples

Queue Manipulation

const (
	accountName   = "MYSTORAGEACCOUNT"
	accountKey    = "ACCOUNT_KEY"
	queueName     = "samplequeue"
)

Exploring Queue Service APIs

// shared key credential set up
cred := azqueue.NewSharedKeyCredential(accountName, accountKey)

// instantiate service client
serviceClient, err := azqueue.NewServiceClientWithSharedKeyCredential(account, cred, nil)
// TODO: handle error

// 1. create queue
queueClient := serviceClient.NewQueueClient(queueName)
_, err = queueClient.Create(context.TODO(), nil)
// TODO: handle error

// 2. enqueue message
_, err = queueClient.EnqueueMessage(context.TODO(), message, nil)
// TODO: handle error

// 3. dequeue message
_, err = queueClient.DequeueMessage(context.TODO(), nil)
// TODO: handle error

// 4. delete queue
_, err =queueClient.Delete(context.TODO(), nil)
// TODO: handle error

Enumerating queues

const (
	account = "https://MYSTORAGEACCOUNT.queue.core.windows.net/"
)

// authenticate with Azure Active Directory
cred, err := azidentity.NewDefaultAzureCredential(nil)
// TODO: handle error

// create a client for the specified storage account
client, err := azqueue.NewServiceClient(account, cred, nil)
// TODO: handle error

// queue listings are returned across multiple pages
pager := client.NewListQueuesPager(nil)

// continue fetching pages until no more remain
for pager.More() {
   resp, err := pager.NextPage(context.Background())
   _require.Nil(err)
   // print queue name
   for _, queue := range resp.Queues {
		fmt.Println(*queue.Name)
	}
}

Troubleshooting

All queue service operations will return an *azcore.ResponseError on failure with a populated ErrorCode field. Many of these errors are recoverable. The queueerror package provides the possible Storage error codes along with various helper facilities for error handling.

const (
	connectionString = "<connection_string>"
	queueName        = "samplequeue"
)

// create a client with the provided connection string
client, err := azqueue.NewServiceClientFromConnectionString(connectionString, nil)
// TODO: handle error

// try to delete the queue, avoiding any potential race conditions with an in-progress or completed deletion
_, err = client.DeleteQueue(context.TODO(), queueName, nil)

if queueerror.HasCode(err, queueerror.QueueBeingDeleted, queueerror.QueueNotFound) {
	// ignore any errors if the queue is being deleted or already has been deleted
} else if err != nil {
	// TODO: some other error
}

Next steps

Get started with our Queue samples. They contain complete examples of the above snippets and more.

Contributing

See the Storage CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.

If you'd like to contribute to this library, please read the [contributing guide] contributing_guide to learn more about how to build and test the code.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

# Packages

No description provided by the author
No description provided by the author

# Functions

NewQueueClient creates an instance of ServiceClient with the specified values.
NewQueueClientFromConnectionString creates an instance of ServiceClient with the specified values.
NewQueueClientWithNoCredential creates an instance of QueueClient with the specified values.
NewQueueClientWithSharedKeyCredential creates an instance of ServiceClient with the specified values.
NewServiceClient creates an instance of ServiceClient with the specified values.
NewServiceClientFromConnectionString creates an instance of ServiceClient with the specified values.
NewServiceClientWithNoCredential creates an instance of ServiceClient with the specified values.
NewServiceClientWithSharedKeyCredential creates an instance of ServiceClient with the specified values.
NewSharedKeyCredential creates an immutable SharedKeyCredential containing the storage account's name and either its primary or secondary key.
ParseURL parses a URL initializing URLParts' fields including any SAS-related & snapshot query parameters.

# Constants

No description provided by the author
No description provided by the author
No description provided by the author

# Structs

ClearMessagesOptions contains the optional parameters for the QueueClient.ClearMessages method.
ClientOptions contains the optional parameters when creating a ServiceClient or QueueClient.
CreateOptions contains the optional parameters for creating a queue.
DeleteMessageOptions contains the optional parameters for the QueueClient.DeleteMessage method.
DeleteOptions contains the optional parameters for deleting a queue.
DequeueMessageOptions contains the optional parameters for the QueueClient.DequeueMessage method.
DequeueMessagesOptions contains the optional parameters for the QueueClient.DequeueMessages method.
EnqueueMessageOptions contains the optional parameters for the QueueClient.EnqueueMessage method.
GetAccessPolicyOptions contains the optional parameters for the QueueClient.GetAccessPolicy method.
GetQueuePropertiesOptions contains the optional parameters for the QueueClient.GetProperties method.
GetSASURLOptions contains the optional parameters for the Client.GetSASURL method.
GetServicePropertiesOptions contains the optional parameters for the ServiceClient.GetServiceProperties method.
GetStatisticsOptions provides set of options for ServiceClient.GetStatistics.
ListQueuesInclude indicates what additional information the service should return with each queue.
ListQueuesOptions provides set of configurations for ListQueues operation.
PeekMessageOptions contains the optional parameters for the QueueClient.PeekMessage method.
PeekMessagesOptions contains the optional parameters for the QueueClient.PeekMessages method.
SetAccessPolicyOptions provides set of configurations for QueueClient.SetAccessPolicy operation.
SetMetadataOptions contains the optional parameters for the QueueClient.SetMetadata method.
SetPropertiesOptions provides set of options for ServiceClient.SetProperties.
UpdateMessageOptions contains the optional parameters for the QueueClient.UpdateMessage method.

# Type aliases

AccessPolicy - An Access policy.
AccessPolicyPermission type simplifies creating the permissions string for a queue's access policy.
ClearMessagesResponse contains the response from method QueueClient.ClearMessages.
CORSRule - CORS is an HTTP feature that enables a web application running under one domain to access resources in another domain.
CreateQueueResponse contains the response from method queue.ServiceClient.Create.
CreateResponse contains the response from method QueueClient.Create.
DeleteMessageResponse contains the response from method QueueClient.DeleteMessage.
DeleteQueueResponse contains the response from method queue.ServiceClient.Delete.
DeleteResponse contains the response from method QueueClient.Delete.
DequeuedMessage - dequeued message.
DequeueMessagesResponse contains the response from method QueueClient.DequeueMessage or QueueClient.DequeueMessages.
EnqueuedMessage - enqueued message.
EnqueueMessagesResponse contains the response from method QueueClient.EnqueueMessage.
GeoReplication - Geo-Replication information for the Secondary Storage Service.
GeoReplicationStatus - The status of the secondary location.
GetAccessPolicyResponse contains the response from method QueueClient.GetAccessPolicy.
GetQueuePropertiesResponse contains the response from method QueueClient.GetProperties.
GetServicePropertiesResponse contains the response from method ServiceClient.GetServiceProperties.
GetStatisticsResponse contains the response from method ServiceClient.GetStatistics.
ListQueuesResponse contains the response from method ServiceClient.ListQueuesSegment.
ListQueuesSegmentResponse - response segment.
Logging - Azure Analytics Logging settings.
Metrics - a summary of request statistics grouped by API in hour or minute aggregates for queues.
PeekedMessage - peeked message.
PeekMessagesResponse contains the response from method QueueClient.PeekMessage or QueueClient.PeekMessages.
Queue - queue item.
RetentionPolicy - the retention policy which determines how long the associated data should persist.
SetAccessPolicyResponse contains the response from method QueueClient.SetAccessPolicy.
SetMetadataResponse contains the response from method QueueClient.SetMetadata.
SetPropertiesResponse contains the response from method ServiceClient.SetProperties.
SharedKeyCredential contains an account's name and its primary or secondary key.
SignedIdentifier - signed identifier.
StorageServiceProperties - Storage Service Properties.
StorageServiceStats - Stats for the storage service.
UpdateMessageResponse contains the response from method QueueClient.UpdateMessage.
URLParts object represents the components that make up an Azure Storage Queue URL.