or run

tessl search

Version

Workspace: tessl
Visibility: Public
Created: 5 days ago
Last updated: about 14 hours ago
Describes: pkg:golang/github.com/Azure/azure-sdk-for-go/sdk/storage/azqueue/v2@v2.0.1

docs

error-handling.md index.md queue-client.md sas.md service-client.md

tile.json

tessl/golang-github-com-azure-azure-sdk-for-go-sdk-storage-azqueue-v2

tessl install tessl/golang-github-com-azure-azure-sdk-for-go-sdk-storage-azqueue-v2@2.0.1

Azure Queue Storage SDK for Go provides comprehensive client library for interacting with Azure's cloud-based message queue service including queue management, message operations, and multiple authentication methods.

Queue Client

QueueClient represents interaction with a specific Azure Storage queue. It provides queue-level operations including message lifecycle management (enqueue, dequeue, peek, update, delete), queue configuration, metadata management, and access control.

Capabilities

Client Creation

Create QueueClient instances with various authentication methods.

// Create queue client with Azure AD credential
func NewQueueClient(queueURL string, cred azcore.TokenCredential, options *ClientOptions) (*QueueClient, error)

// Create queue client with shared key credential
func NewQueueClientWithSharedKeyCredential(queueURL string, cred *SharedKeyCredential, options *ClientOptions) (*QueueClient, error)

// Create queue client from connection string
func NewQueueClientFromConnectionString(connectionString string, queueName string, options *ClientOptions) (*QueueClient, error)

// Create queue client for anonymous/SAS access
func NewQueueClientWithNoCredential(queueURL string, options *ClientOptions) (*QueueClient, error)

Usage Examples:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azqueue/v2"
)

// Azure AD authentication (recommended)
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
    // handle error
}
queueClient, err := azqueue.NewQueueClient(
    "https://myaccount.queue.core.windows.net/myqueue",
    cred,
    nil,
)

// Shared key authentication
sharedKeyCred, err := azqueue.NewSharedKeyCredential("myaccount", "mykey")
if err != nil {
    // handle error
}
queueClient, err = azqueue.NewQueueClientWithSharedKeyCredential(
    "https://myaccount.queue.core.windows.net/myqueue",
    sharedKeyCred,
    nil,
)

// Connection string authentication
queueClient, err = azqueue.NewQueueClientFromConnectionString(
    "DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net",
    "myqueue",
    nil,
)

// No credential (for SAS URLs)
queueClient, err = azqueue.NewQueueClientWithNoCredential(
    "https://myaccount.queue.core.windows.net/myqueue?<sas-token>",
    nil,
)

Get Queue URL

Retrieve the queue endpoint URL.

func (q *QueueClient) URL() string

Usage:

url := queueClient.URL()
// Returns: "https://myaccount.queue.core.windows.net/myqueue"

Queue Management Operations

Create Queue

Create the queue.

func (q *QueueClient) Create(ctx context.Context, options *CreateOptions) (CreateResponse, error)

// Options for queue creation
type CreateOptions struct {
    // Optional. User-defined name-value pairs associated with the queue
    Metadata map[string]*string
}

// Response type
type CreateResponse = generated.QueueClientCreateResponse

Usage:

import "context"

// Create queue without metadata
_, err := queueClient.Create(context.TODO(), nil)
if err != nil {
    // handle error
}

// Create queue with metadata
metadata := map[string]*string{
    "department": to.Ptr("engineering"),
    "owner":      to.Ptr("alice@example.com"),
}
_, err = queueClient.Create(context.TODO(), &azqueue.CreateOptions{
    Metadata: metadata,
})

Notes:

If queue exists with identical metadata, returns 204 (No Content)
If queue exists with different metadata, returns 409 (Conflict)

Delete Queue

Delete the queue.

func (q *QueueClient) Delete(ctx context.Context, options *DeleteOptions) (DeleteResponse, error)

// Options for queue deletion
type DeleteOptions struct {
    // Empty struct - no options currently available
}

// Response type
type DeleteResponse = generated.QueueClientDeleteResponse

Usage:

_, err := queueClient.Delete(context.TODO(), nil)
if err != nil {
    // handle error
}

Get Queue Properties

Retrieve queue properties including metadata and approximate message count.

func (q *QueueClient) GetProperties(ctx context.Context, options *GetQueuePropertiesOptions) (GetQueuePropertiesResponse, error)

// Options for getting properties
type GetQueuePropertiesOptions struct {
    // Empty struct - no options currently available
}

// Response type
type GetQueuePropertiesResponse = generated.QueueClientGetPropertiesResponse

Usage:

resp, err := queueClient.GetProperties(context.TODO(), nil)
if err != nil {
    // handle error
}

fmt.Printf("Approximate message count: %d\n", *resp.ApproximateMessagesCount)
if resp.Metadata != nil {
    for key, value := range resp.Metadata {
        fmt.Printf("Metadata %s: %s\n", key, *value)
    }
}

Set Queue Metadata

Set user-defined metadata on the queue.

func (q *QueueClient) SetMetadata(ctx context.Context, options *SetMetadataOptions) (SetMetadataResponse, error)

// Options for setting metadata
type SetMetadataOptions struct {
    // User-defined metadata name-value pairs
    Metadata map[string]*string
}

// Response type
type SetMetadataResponse = generated.QueueClientSetMetadataResponse

Usage:

metadata := map[string]*string{
    "updated":    to.Ptr(time.Now().Format(time.RFC3339)),
    "department": to.Ptr("sales"),
}

_, err := queueClient.SetMetadata(context.TODO(), &azqueue.SetMetadataOptions{
    Metadata: metadata,
})
if err != nil {
    // handle error
}

Notes:

Metadata names must be valid HTTP headers (ASCII only)
Metadata names are case-insensitive
Base64-encode or URL-encode metadata values containing non-ASCII characters

Access Control Operations

Get Access Policy

Retrieve the queue's access policy.

func (q *QueueClient) GetAccessPolicy(ctx context.Context, o *GetAccessPolicyOptions) (GetAccessPolicyResponse, error)

// Options for getting access policy
type GetAccessPolicyOptions struct {
    // Empty struct - no options currently available
}

// Response type
type GetAccessPolicyResponse = generated.QueueClientGetAccessPolicyResponse

// Signed identifier
type SignedIdentifier = generated.SignedIdentifier

// Access policy
type AccessPolicy = generated.AccessPolicy

Usage:

resp, err := queueClient.GetAccessPolicy(context.TODO(), nil)
if err != nil {
    // handle error
}

for _, policy := range resp.SignedIdentifiers {
    fmt.Printf("Policy ID: %s\n", *policy.ID)
    if policy.AccessPolicy != nil {
        fmt.Printf("  Start: %s\n", policy.AccessPolicy.Start.Format(time.RFC3339))
        fmt.Printf("  Expiry: %s\n", policy.AccessPolicy.Expiry.Format(time.RFC3339))
        fmt.Printf("  Permission: %s\n", *policy.AccessPolicy.Permission)
    }
}

Set Access Policy

Set the queue's access policy with signed identifiers.

func (q *QueueClient) SetAccessPolicy(ctx context.Context, o *SetAccessPolicyOptions) (SetAccessPolicyResponse, error)

// Options for setting access policy
type SetAccessPolicyOptions struct {
    // Access control list with signed identifiers
    QueueACL []*SignedIdentifier
}

// Response type
type SetAccessPolicyResponse = generated.QueueClientSetAccessPolicyResponse

Usage:

import "time"

// Create signed identifier with access policy
signedIdentifier := &azqueue.SignedIdentifier{
    ID: to.Ptr("policy1"),
    AccessPolicy: &azqueue.AccessPolicy{
        Start:      to.Ptr(time.Now()),
        Expiry:     to.Ptr(time.Now().Add(24 * time.Hour)),
        Permission: to.Ptr("raup"), // read, add, update, process
    },
}

_, err := queueClient.SetAccessPolicy(context.TODO(), &azqueue.SetAccessPolicyOptions{
    QueueACL: []*azqueue.SignedIdentifier{signedIdentifier},
})
if err != nil {
    // handle error
}

Notes:

Maximum 5 access policies per queue
Permission string: r (read), a (add), u (update), p (process)
Used with SAS tokens to centrally manage access without regenerating SAS

Message Operations

Enqueue Message

Add a message to the queue.

func (q *QueueClient) EnqueueMessage(ctx context.Context, content string, o *EnqueueMessageOptions) (EnqueueMessagesResponse, error)

// Options for enqueuing message
type EnqueueMessageOptions struct {
    // Time-to-live in seconds (-1 for infinite, default: 7 days)
    TimeToLive *int32

    // Initial visibility timeout in seconds (0 to 7 days, default: 0)
    VisibilityTimeout *int32
}

// Response type
type EnqueueMessagesResponse = generated.MessagesClientEnqueueResponse

// Enqueued message information
type EnqueuedMessage = generated.EnqueuedMessage

Usage:

// Simple enqueue
_, err := queueClient.EnqueueMessage(
    context.TODO(),
    "Hello, Queue!",
    nil,
)
if err != nil {
    // handle error
}

// Enqueue with options
resp, err := queueClient.EnqueueMessage(
    context.TODO(),
    "Delayed message",
    &azqueue.EnqueueMessageOptions{
        TimeToLive:        to.Ptr(int32(3600)),      // 1 hour TTL
        VisibilityTimeout: to.Ptr(int32(60)),        // Visible after 60 seconds
    },
)
if err != nil {
    // handle error
}

// Access enqueued message info
for _, msg := range resp.Messages {
    fmt.Printf("Message ID: %s\n", *msg.MessageID)
    fmt.Printf("Pop Receipt: %s\n", *msg.PopReceipt)
    fmt.Printf("Insertion Time: %s\n", msg.InsertionTime.Format(time.RFC3339))
    fmt.Printf("Expiration Time: %s\n", msg.ExpirationTime.Format(time.RFC3339))
}

Notes:

Maximum message size: 64 KiB
Message content must be UTF-8 or Base64-encoded
TimeToLive of -1 means message never expires
Default TimeToLive is 7 days if not specified

Dequeue Message (Single)

Remove and retrieve one message from the queue.

func (q *QueueClient) DequeueMessage(ctx context.Context, o *DequeueMessageOptions) (DequeueMessagesResponse, error)

// Options for dequeuing single message
type DequeueMessageOptions struct {
    // Visibility timeout in seconds (0 to 7 days, default: 30)
    VisibilityTimeout *int32
}

// Response type (same as DequeueMessages)
type DequeueMessagesResponse = generated.MessagesClientDequeueResponse

// Dequeued message information
type DequeuedMessage = generated.DequeuedMessage

Usage:

// Dequeue single message with default visibility timeout
resp, err := queueClient.DequeueMessage(context.TODO(), nil)
if err != nil {
    // handle error
}

if len(resp.Messages) > 0 {
    msg := resp.Messages[0]
    fmt.Printf("Message: %s\n", *msg.MessageText)
    fmt.Printf("Message ID: %s\n", *msg.MessageID)
    fmt.Printf("Pop Receipt: %s\n", *msg.PopReceipt)
    fmt.Printf("Dequeue Count: %d\n", *msg.DequeueCount)

    // Process message...

    // Delete after processing
    _, err = queueClient.DeleteMessage(
        context.TODO(),
        *msg.MessageID,
        *msg.PopReceipt,
        nil,
    )
}

Dequeue Messages (Multiple)

Remove and retrieve multiple messages from the queue (up to 32).

func (q *QueueClient) DequeueMessages(ctx context.Context, o *DequeueMessagesOptions) (DequeueMessagesResponse, error)

// Options for dequeuing multiple messages
type DequeueMessagesOptions struct {
    // Number of messages to retrieve (1 to 32, default: 1)
    NumberOfMessages *int32

    // Visibility timeout in seconds (1 to 7 days, default: 30)
    VisibilityTimeout *int32
}

Usage:

// Dequeue up to 10 messages
resp, err := queueClient.DequeueMessages(context.TODO(), &azqueue.DequeueMessagesOptions{
    NumberOfMessages:  to.Ptr(int32(10)),
    VisibilityTimeout: to.Ptr(int32(60)), // 60 seconds
})
if err != nil {
    // handle error
}

// Process all dequeued messages
for _, msg := range resp.Messages {
    fmt.Printf("Message: %s\n", *msg.MessageText)

    // Process message...

    // Delete after successful processing
    _, err = queueClient.DeleteMessage(
        context.TODO(),
        *msg.MessageID,
        *msg.PopReceipt,
        nil,
    )
}

Notes:

Dequeued messages become invisible to other consumers for the visibility timeout duration
If message is not deleted before visibility timeout expires, it becomes visible again
DequeueCount tracks how many times a message has been dequeued
Use PopReceipt to delete or update the message

Peek Message (Single)

View the first message without removing it from the queue.

func (q *QueueClient) PeekMessage(ctx context.Context, o *PeekMessageOptions) (PeekMessagesResponse, error)

// Options for peeking single message
type PeekMessageOptions struct {
    // Empty struct - no options currently available
}

// Response type (same as PeekMessages)
type PeekMessagesResponse = generated.MessagesClientPeekResponse

// Peeked message information
type PeekedMessage = generated.PeekedMessage

Usage:

resp, err := queueClient.PeekMessage(context.TODO(), nil)
if err != nil {
    // handle error
}

if len(resp.Messages) > 0 {
    msg := resp.Messages[0]
    fmt.Printf("Message: %s\n", *msg.MessageText)
    fmt.Printf("Message ID: %s\n", *msg.MessageID)
    fmt.Printf("Dequeue Count: %d\n", *msg.DequeueCount)
}

Notes:

Peeked messages remain visible in the queue
No PopReceipt is provided since message is not locked
Cannot update or delete a peeked message without dequeuing it first

Peek Messages (Multiple)

View multiple messages without removing them from the queue (up to 32).

func (q *QueueClient) PeekMessages(ctx context.Context, o *PeekMessagesOptions) (PeekMessagesResponse, error)

// Options for peeking multiple messages
type PeekMessagesOptions struct {
    // Number of messages to peek (1 to 32)
    NumberOfMessages *int32
}

Usage:

// Peek at up to 10 messages
resp, err := queueClient.PeekMessages(context.TODO(), &azqueue.PeekMessagesOptions{
    NumberOfMessages: to.Ptr(int32(10)),
})
if err != nil {
    // handle error
}

for i, msg := range resp.Messages {
    fmt.Printf("Message %d: %s\n", i+1, *msg.MessageText)
}

Update Message

Update a message's content and/or visibility timeout.

func (q *QueueClient) UpdateMessage(ctx context.Context, messageID string, popReceipt string, content string, o *UpdateMessageOptions) (UpdateMessageResponse, error)

// Options for updating message
type UpdateMessageOptions struct {
    // New visibility timeout in seconds (0 to 7 days)
    VisibilityTimeout *int32
}

// Response type
type UpdateMessageResponse = generated.MessageIDClientUpdateResponse

Usage:

// First, dequeue a message
deqResp, err := queueClient.DequeueMessage(context.TODO(), nil)
if err != nil {
    // handle error
}

if len(deqResp.Messages) > 0 {
    msg := deqResp.Messages[0]

    // Update message content
    updResp, err := queueClient.UpdateMessage(
        context.TODO(),
        *msg.MessageID,
        *msg.PopReceipt,
        "Updated content",
        nil,
    )
    if err != nil {
        // handle error
    }

    // Use new PopReceipt for subsequent operations
    newPopReceipt := *updResp.PopReceipt
    fmt.Printf("New Pop Receipt: %s\n", newPopReceipt)
}

Usage (extend visibility timeout):

// Extend visibility timeout to continue processing
updResp, err := queueClient.UpdateMessage(
    context.TODO(),
    messageID,
    popReceipt,
    messageText, // Keep same content
    &azqueue.UpdateMessageOptions{
        VisibilityTimeout: to.Ptr(int32(60)), // Extend by 60 seconds
    },
)
if err != nil {
    // handle error
}

// Use new PopReceipt
popReceipt = *updResp.PopReceipt

Notes:

PopReceipt changes with each update
Must use the latest PopReceipt for subsequent operations
Can update content, visibility timeout, or both
Visibility timeout is relative to the current time, not the original dequeue time

Delete Message

Delete a message from the queue.

func (q *QueueClient) DeleteMessage(ctx context.Context, messageID string, popReceipt string, o *DeleteMessageOptions) (DeleteMessageResponse, error)

// Options for deleting message
type DeleteMessageOptions struct {
    // Empty struct - no options currently available
}

// Response type
type DeleteMessageResponse = generated.MessageIDClientDeleteResponse

Usage:

// Dequeue and delete
resp, err := queueClient.DequeueMessage(context.TODO(), nil)
if err != nil {
    // handle error
}

if len(resp.Messages) > 0 {
    msg := resp.Messages[0]

    // Process message...

    // Delete message
    _, err = queueClient.DeleteMessage(
        context.TODO(),
        *msg.MessageID,
        *msg.PopReceipt,
        nil,
    )
    if err != nil {
        // handle error
    }
}

Notes:

Must have valid PopReceipt (from dequeue or update operation)
Message must still be invisible (within visibility timeout)
Always delete messages after successful processing to prevent reprocessing

Clear Messages

Delete all messages from the queue.

func (q *QueueClient) ClearMessages(ctx context.Context, o *ClearMessagesOptions) (ClearMessagesResponse, error)

// Options for clearing messages
type ClearMessagesOptions struct {
    // Empty struct - no options currently available
}

// Response type
type ClearMessagesResponse = generated.MessagesClientClearResponse

Usage:

_, err := queueClient.ClearMessages(context.TODO(), nil)
if err != nil {
    // handle error
}
fmt.Println("All messages cleared from queue")

Notes:

Deletes all messages regardless of visibility state
Cannot be undone
Queue itself remains (only messages are deleted)

SAS URL Generation

Generate a SAS URL for queue-level access.

func (q *QueueClient) GetSASURL(permissions sas.QueuePermissions, expiry time.Time, o *GetSASURLOptions) (string, error)

// Options for SAS URL generation
type GetSASURLOptions struct {
    // Optional start time for SAS validity
    StartTime *time.Time
}

Usage:

import (
    "time"
    "github.com/Azure/azure-sdk-for-go/sdk/storage/azqueue/v2/sas"
)

// Define permissions
permissions := sas.QueuePermissions{
    Read:    true,
    Add:     true,
    Update:  true,
    Process: true,
}

// Generate SAS URL valid for 1 hour
expiry := time.Now().Add(1 * time.Hour)
sasURL, err := queueClient.GetSASURL(permissions, expiry, nil)
if err != nil {
    // handle error
}

fmt.Println(sasURL)
// Use sasURL to create a new client with SAS authentication

Notes:

Only works if QueueClient was created with SharedKeyCredential
Permissions: r (read/peek), a (add), u (update), p (process/dequeue+delete)

Version

tessl/golang-github-com-azure-azure-sdk-for-go-sdk-storage-azqueue-v2

queue-client.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Queue Client

Capabilities

Client Creation

Get Queue URL

Queue Management Operations

Create Queue

Delete Queue

Get Queue Properties

Set Queue Metadata

Access Control Operations

Get Access Policy

Set Access Policy

Message Operations

Enqueue Message

Dequeue Message (Single)

Dequeue Messages (Multiple)

Peek Message (Single)

Peek Messages (Multiple)

Update Message

Delete Message

Clear Messages

SAS URL Generation

queue-client.mddocs/