Skip to content

Commit a9e3d56

Browse files
tasherif-msftjhendrixMSFT
tasherif-msft
and
jhendrixMSFT
authored
AzQueue (Azure#20013)
* Generate Code for AzQueue (Azure#19729) * first generation * removed queuename from url param * fixed georep * removed pagination * move to internal * last generation * [Feature] Queue Service Client + Key Credential Authentication (Azure#19732) * first generation * removed queuename from url param * fixed georep * removed pagination * added basic methods * added basic models * regenrated and added pager * regenrated and added pager * autorest comment change * comments * comments * comments * version change * marker * rename to queue * further cleanup * rename service client * add license * Enable CI for azqueue (Azure#19835) * Update to latest code generator for azqueue (Azure#19837) * Update to latest code generator for azqueue Add build.go and format generated code. * add changelog * [Feature] SAS Support + Test Framework (Azure#19756) * first generation * removed queuename from url param * fixed georep * removed pagination * added basic methods * added basic models * regenrated and added pager * regenrated and added pager * autorest comment change * comments * comments * comments * added sas perms and basic tests * spell check * cleanup * version change * added sas method for service client * uncomment test * cleanup * cleanup * sas test * cleanup * new test framework * update internal module to support test assets * set code coverage floor * fixed linter Co-authored-by: Joel Hendrix <jhendrix@microsoft.com> * Queue Client + More Tests (Azure#19852) * added basic queue client * added create and delete queue * added tests to service client for queues * added test to ensure pagination behaves correctly * updated tests * added TODOs * more tests * assets * lint * added more queue methods * more methods * added tests * export * export * export * added more tests * cleanup * address comments * removed message id from composite * removed account services and cleaned up * renamed cors * renamed cors * fixed cors test failure * lint * Queues Live Pipeline + APIViews Feedback (Azure#19955) * removed item suffix * test resources file * lint fix * renamed queues list * fix * More Service Client and Queue Client Tests (Azure#19958) * removed item suffix * test resources file * lint fix * added more service client tests * added more service client tests * fix tests * fix tests * added more message related tests * added peek message tests * cleaup * added tests for clear and delete * added update tests * more code coverage * cleanup * added stats test * added one more test * removed test * added client tests * more sas tests * more tests * AzQueue Public Preview APIVIew Feedback (Azure#20003) * Resolve APIView feedback for Public Preview * test * More api view comments * expose GRS * constants * tests * cleanup * Changelog Entry + doc.go File + Basic Samples (Azure#20004) * added basic doc * added a doc.go file * sample todos * added readme file * readme update * cleanup * cleanup * added samples * go update * go update * link fix --------- Co-authored-by: Joel Hendrix <jhendrix@microsoft.com>
1 parent b19ab71 commit a9e3d56

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+9410
-5
lines changed

‎eng/config.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@
2424
"Name": "azidentity",
2525
"CoverageGoal": 0.68
2626
},
27+
{
28+
"Name": "azqueue",
29+
"CoverageGoal": 0.60
30+
},
2731
{
2832
"Name": "aztemplate",
2933
"CoverageGoal": 0.50

‎sdk/storage/azblob/container/client.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ func (c *Client) Restore(ctx context.Context, deletedContainerVersion string, op
190190
// For more information, see https://docs.microsoft.com/rest/api/storageservices/get-container-metadata.
191191
func (c *Client) GetProperties(ctx context.Context, o *GetPropertiesOptions) (GetPropertiesResponse, error) {
192192
// NOTE: GetMetadata actually calls GetProperties internally because GetProperties returns the metadata AND the properties.
193-
// This allows us to not expose a GetProperties method at all simplifying the API.
193+
// This allows us to not expose a GetMetadata method at all simplifying the API.
194194
// The optionals are nil, like they were in track 1.5
195195
opts, leaseAccessConditions := o.format()
196196

‎sdk/storage/azblob/sas/account.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ func (v AccountSignatureValues) SignWithSharedKey(sharedKeyCredential *SharedKey
9090
}
9191

9292
// AccountPermissions type simplifies creating the permissions string for an Azure Storage Account SAS.
93-
// Initialize an instance of this type and then call Client.GetSASURL with it or use the String method to set AccountSASSignatureValues Permissions field.
93+
// Initialize an instance of this type and then call its String method to set AccountSASSignature value's Permissions field.
9494
type AccountPermissions struct {
9595
Read, Write, Delete, DeletePreviousVersion, PermanentDelete, List, Add, Create, Update, Process, FilterByTags, Tag, SetImmutabilityPolicy bool
9696
}

‎sdk/storage/azblob/sas/service.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -261,7 +261,7 @@ func getCanonicalName(account string, containerName string, blobName string, dir
261261
}
262262

263263
// ContainerPermissions type simplifies creating the permissions string for an Azure Storage container SAS.
264-
// Initialize an instance of this type and then call Client.GetSASURL with it or use the String method to set BlobSASSignatureValues Permissions field.
264+
// Initialize an instance of this type and then call its String method to set BlobSASSignatureValues' Permissions field.
265265
// All permissions descriptions can be found here: https://docs.microsoft.com/en-us/rest/api/storageservices/create-service-sas#permissions-for-a-directory-container-or-blob
266266
type ContainerPermissions struct {
267267
Read, Add, Create, Write, Delete, DeletePreviousVersion, List, FilterByTags, Move, SetImmutabilityPolicy bool
@@ -353,13 +353,13 @@ func parseContainerPermissions(s string) (ContainerPermissions, error) {
353353
}
354354

355355
// BlobPermissions type simplifies creating the permissions string for an Azure Storage blob SAS.
356-
// Initialize an instance of this type and then call Client.GetSASURL with it or use the String method to set BlobSASSignatureValues Permissions field.
356+
// Initialize an instance of this type and then call its String method to set BlobSASSignatureValues' Permissions field.
357357
type BlobPermissions struct {
358358
Read, Add, Create, Write, Delete, DeletePreviousVersion, PermanentDelete, List, Tag, Move, Execute, Ownership, Permissions, SetImmutabilityPolicy bool
359359
}
360360

361361
// String produces the SAS permissions string for an Azure Storage blob.
362-
// Call this method to set BlobSignatureValue's Permissions field.
362+
// Call this method to set BlobSignatureValues' Permissions field.
363363
func (p *BlobPermissions) String() string {
364364
var b bytes.Buffer
365365
if p.Read {

‎sdk/storage/azqueue/CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## 0.1.0 (2023-02-15)
2+
3+
### Features Added
4+
5+
* This is the initial preview release of the `azqueue` library

‎sdk/storage/azqueue/LICENSE.txt‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) Microsoft Corporation. All rights reserved.
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE

‎sdk/storage/azqueue/README.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Azure Queue Storage SDK for Go
2+
3+
> Server Version: 2018-03-28
4+
5+
Azure Queue storage is a service for storing large numbers of messages that can be accessed from anywhere in
6+
the world via authenticated calls using HTTP or HTTPS.
7+
A single queue message can be up to 64 KiB in size, and a queue can contain millions of messages,
8+
up to the total capacity limit of a storage account.
9+
10+
[Source code][source] | [API reference documentation][docs] | [REST API documentation][rest_docs]
11+
12+
## Getting started
13+
14+
### Install the package
15+
16+
Install the Azure Queue Storage SDK for Go with [go get][goget]:
17+
18+
```Powershell
19+
go get github.com/Azure/azure-sdk-for-go/sdk/storage/azqueue
20+
```
21+
22+
If you're going to authenticate with Azure Active Directory (recommended), install the [azidentity][azidentity] module.
23+
```Powershell
24+
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
25+
```
26+
27+
### Prerequisites
28+
29+
A supported [Go][godevdl] version (the Azure SDK supports the two most recent Go releases).
30+
31+
You need an [Azure subscription][azure_sub] and a
32+
[Storage Account][storage_account_docs] to use this package.
33+
34+
To create a new Storage Account, you can use the [Azure Portal][storage_account_create_portal],
35+
[Azure PowerShell][storage_account_create_ps], or the [Azure CLI][storage_account_create_cli].
36+
Here's an example using the Azure CLI:
37+
38+
```Powershell
39+
az storage account create --name MyStorageAccount --resource-group MyResourceGroup --location westus --sku Standard_LRS
40+
```
41+
42+
### Authenticate the client
43+
44+
In order to interact with the Azure Queue Storage service, you'll need to create an instance of the `azqueue.ServiceClient` type. The [azidentity][azidentity] module makes it easy to add Azure Active Directory support for authenticating Azure SDK clients with their corresponding Azure services.
45+
46+
```go
47+
// create a credential for authenticating with Azure Active Directory
48+
cred, err := azidentity.NewDefaultAzureCredential(nil)
49+
// TODO: handle err
50+
51+
// create an azqueue.ServiceClient for the specified storage account that uses the above credential
52+
client, err := azqueue.NewServiceClient("https://MYSTORAGEACCOUNT.queue.core.windows.net/", cred, nil)
53+
// TODO: handle err
54+
```
55+
56+
Learn more about enabling Azure Active Directory for authentication with Azure Storage in [our documentation][storage_ad] and [our samples](#next-steps).
57+
58+
## Key concepts
59+
The following components make up the Azure Queue Service:
60+
* The storage account itself
61+
* A queue within the storage account, which contains a set of messages
62+
* A message within a queue, in any format, of up to 64 KiB
63+
64+
The Azure Storage Queues client library for GO allows you to interact with each of these components through the
65+
use of a dedicated client object.
66+
67+
### Clients
68+
Two different clients are provided to interact with the various components of the Queue Service:
69+
1. ServiceClient -
70+
this client represents interaction with the Azure storage account itself, and allows you to acquire preconfigured
71+
client instances to access the queues within. It provides operations to retrieve and configure the account
72+
properties as well as list, create, and delete queues within the account. To perform operations on a specific queue,
73+
retrieve a client using the `NewQueueClient` method.
74+
2. QueueClient -
75+
this client represents interaction with a specific queue (which need not exist yet). It provides operations to
76+
create, delete, or configure a queue and includes operations to enqueue, dequeue, peek, delete, and update messages
77+
within it.
78+
79+
### Messages
80+
* **Enqueue** - Adds a message to the queue and optionally sets a visibility timeout for the message.
81+
* **Dequeue** - Retrieves a message from the queue and makes it invisible to other consumers.
82+
* **Peek** - Retrieves a message from the front of the queue, without changing the message visibility.
83+
* **Update** - Updates the visibility timeout of a message and/or the message contents.
84+
* **Delete** - Deletes a specified message from the queue.
85+
* **Clear** - Clears all messages from the queue.
86+
87+
### Goroutine safety
88+
We guarantee that all client instance methods are goroutine-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/golang_introduction.html#thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across goroutines.
89+
90+
### About Queue metadata
91+
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.
92+
93+
### Additional concepts
94+
<!-- CLIENT COMMON BAR -->
95+
[Client options](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore/policy#ClientOptions) |
96+
[Accessing the response](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore/runtime#WithCaptureResponse) |
97+
[Handling failures](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore#ResponseError) |
98+
[Logging](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore/log)
99+
<!-- CLIENT COMMON BAR -->
100+
101+
## Examples
102+
103+
### Queue Manipulation
104+
105+
```go
106+
const (
107+
accountName = "MYSTORAGEACCOUNT"
108+
accountKey = "ACCOUNT_KEY"
109+
queueName = "samplequeue"
110+
)
111+
```
112+
113+
### Exploring Queue Service APIs
114+
115+
```go
116+
// shared key credential set up
117+
cred := azqueue.NewSharedKeyCredential(accountName, accountKey)
118+
119+
// instantiate service client
120+
serviceClient, err := azqueue.NewServiceClientWithSharedKeyCredential(account, cred, nil)
121+
// TODO: handle error
122+
123+
// 1. create queue
124+
queueClient := serviceClient.NewQueueClient(queueName)
125+
_, err = queueClient.Create(context.TODO(), nil)
126+
// TODO: handle error
127+
128+
// 2. enqueue message
129+
_, err = queueClient.EnqueueMessage(context.TODO(), message, nil)
130+
// TODO: handle error
131+
132+
// 3. dequeue message
133+
_, err = queueClient.DequeueMessage(context.TODO(), nil)
134+
// TODO: handle error
135+
136+
// 4. delete queue
137+
_, err =queueClient.Delete(context.TODO(), nil)
138+
// TODO: handle error
139+
```
140+
141+
### Enumerating queues
142+
143+
```go
144+
const (
145+
account = "https://MYSTORAGEACCOUNT.queue.core.windows.net/"
146+
)
147+
148+
// authenticate with Azure Active Directory
149+
cred, err := azidentity.NewDefaultAzureCredential(nil)
150+
// TODO: handle error
151+
152+
// create a client for the specified storage account
153+
client, err := azqueue.NewServiceClient(account, cred, nil)
154+
// TODO: handle error
155+
156+
// queue listings are returned across multiple pages
157+
pager := client.NewListQueuesPager(nil)
158+
159+
// continue fetching pages until no more remain
160+
for pager.More() {
161+
resp, err := pager.NextPage(context.Background())
162+
_require.Nil(err)
163+
// print queue name
164+
for _, queue := range resp.Queues {
165+
fmt.Println(*queue.Name)
166+
}
167+
}
168+
```
169+
170+
## Troubleshooting
171+
172+
All queue service operations will return an
173+
[*azcore.ResponseError][azcore_response_error] on failure with a
174+
populated `ErrorCode` field. Many of these errors are recoverable.
175+
The [queueerror][queue_error] package provides the possible Storage error codes
176+
along with various helper facilities for error handling.
177+
178+
```go
179+
const (
180+
connectionString = "<connection_string>"
181+
queueName = "samplequeue"
182+
)
183+
184+
// create a client with the provided connection string
185+
client, err := azqueue.NewServiceClientFromConnectionString(connectionString, nil)
186+
// TODO: handle error
187+
188+
// try to delete the queue, avoiding any potential race conditions with an in-progress or completed deletion
189+
_, err = client.DeleteQueue(context.TODO(), queueName, nil)
190+
191+
if queueerror.HasCode(err, queueerror.QueueBeingDeleted, queueerror.QueueNotFound) {
192+
// ignore any errors if the queue is being deleted or already has been deleted
193+
} else if err != nil {
194+
// TODO: some other error
195+
}
196+
```
197+
198+
## Next steps
199+
200+
Get started with our [Queue samples][samples]. They contain complete examples of the above snippets and more.
201+
202+
## Contributing
203+
204+
See the [Storage CONTRIBUTING.md][storage_contrib] for details on building,
205+
testing, and contributing to this library.
206+
207+
This project welcomes contributions and suggestions. Most contributions require
208+
you to agree to a Contributor License Agreement (CLA) declaring that you have
209+
the right to, and actually do, grant us the rights to use your contribution. For
210+
details, visit [cla.microsoft.com][cla].
211+
212+
This project has adopted the [Microsoft Open Source Code of Conduct][coc].
213+
For more information see the [Code of Conduct FAQ][coc_faq]
214+
or contact [opencode@microsoft.com][coc_contact] with any
215+
additional questions or comments.
216+
217+
<!-- LINKS -->
218+
[source]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/storage/azqueue
219+
[docs]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azqueue
220+
[rest_docs]: https://docs.microsoft.com/rest/api/storageservices/queue-service-rest-api
221+
[godevdl]: https://go.dev/dl/
222+
[goget]: https://pkg.go.dev/cmd/go#hdr-Add_dependencies_to_current_module_and_install_them
223+
[storage_account_docs]: https://docs.microsoft.com/azure/storage/common/storage-account-overview
224+
[storage_account_create_ps]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-powershell
225+
[storage_account_create_cli]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-cli
226+
[storage_account_create_portal]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal
227+
[azure_cli]: https://docs.microsoft.com/cli/azure
228+
[azure_sub]: https://azure.microsoft.com/free/
229+
[azidentity]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity
230+
[storage_ad]: https://docs.microsoft.com/azure/storage/common/storage-auth-aad
231+
[azcore_response_error]: https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore#ResponseError
232+
[samples]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/storage/azqueue/samples_test.go
233+
[queue_error]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/storage/azqueue/queueerror/error_codes.go
234+
[queue]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/storage/azqueue/queue_client.go
235+
[sas]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/storage/azqueue/sas
236+
[service]: https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/storage/azqueue/service_client.go
237+
[storage_contrib]: https://github.com/Azure/azure-sdk-for-go/blob/main/CONTRIBUTING.md
238+
[cla]: https://cla.microsoft.com
239+
[coc]: https://opensource.microsoft.com/codeofconduct/
240+
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
241+
[coc_contact]: mailto:opencode@microsoft.com

‎sdk/storage/azqueue/assets.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"AssetsRepo": "Azure/azure-sdk-assets",
3+
"AssetsRepoPrefixPath": "go",
4+
"TagPrefix": "go/storage/azqueue",
5+
"Tag": "go/storage/azqueue_250a75f53b"
6+
}

‎sdk/storage/azqueue/ci.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
trigger:
2+
branches:
3+
include:
4+
- main
5+
- feature/*
6+
- hotfix/*
7+
- release/*
8+
paths:
9+
include:
10+
- sdk/storage/azqueue
11+
12+
pr:
13+
branches:
14+
include:
15+
- main
16+
- feature/*
17+
- hotfix/*
18+
- release/*
19+
paths:
20+
include:
21+
- sdk/storage/azqueue
22+
23+
24+
stages:
25+
- template: /eng/pipelines/templates/jobs/archetype-sdk-client.yml
26+
parameters:
27+
ServiceDirectory: 'storage/azqueue'
28+
RunLiveTests: true

‎sdk/storage/azqueue/constants.go‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
//go:build go1.18
2+
// +build go1.18
3+
4+
// Copyright (c) Microsoft Corporation. All rights reserved.
5+
// Licensed under the MIT License. See License.txt in the project root for license information.
6+
7+
package azqueue
8+
9+
import "github.com/Azure/azure-sdk-for-go/sdk/storage/azqueue/internal/generated"
10+
11+
// GeoReplicationStatus - The status of the secondary location
12+
type GeoReplicationStatus = generated.GeoReplicationStatus
13+
14+
const (
15+
GeoReplicationStatusLive GeoReplicationStatus = generated.GeoReplicationStatusLive
16+
GeoReplicationStatusBootstrap GeoReplicationStatus = generated.GeoReplicationStatusBootstrap
17+
GeoReplicationStatusUnavailable GeoReplicationStatus = generated.GeoReplicationStatusUnavailable
18+
)

0 commit comments

Comments
 (0)