|
| 1 | +# Azure Queue client library for Rust |
| 2 | + |
| 3 | +Azure Queue Storage is a service for storing large numbers of messages. |
| 4 | + |
| 5 | +[Source code] | [Package (crates.io)] | [API reference documentation] | [REST API documentation] | [Product documentation] |
| 6 | + |
| 7 | +## Getting started |
| 8 | + |
| 9 | +**⚠️ Note: The `azure_storage_queue` crate is currently under active development and not all features may be implemented or work as intended. This crate is in beta and not suitable for Production environments. For any general feedback or usage issues, please open a GitHub issue [here](https://github.com/Azure/azure-sdk-for-rust/issues).** |
| 10 | + |
| 11 | +### Install the package |
| 12 | + |
| 13 | +Install the Azure Storage Queue client library for Rust with [cargo]: |
| 14 | + |
| 15 | +```sh |
| 16 | +cargo add azure_storage_queue |
| 17 | +``` |
| 18 | + |
| 19 | +### Prerequisites |
| 20 | + |
| 21 | +* You must have an [Azure subscription] and an [Azure storage account] to use this package. |
| 22 | + |
| 23 | +### Create a storage account |
| 24 | + |
| 25 | +If you wish to create a new storage account, you can use the |
| 26 | +[Azure Portal], [Azure PowerShell], or [Azure CLI]: |
| 27 | + |
| 28 | +```sh |
| 29 | +# Create a new resource group to hold the storage account - |
| 30 | +# if using an existing resource group, skip this step |
| 31 | +az group create --name my-resource-group --location westus2 |
| 32 | + |
| 33 | +# Create the storage account |
| 34 | +az storage account create -n my-storage-account-name -g my-resource-group |
| 35 | +``` |
| 36 | + |
| 37 | +#### Authenticate the client |
| 38 | + |
| 39 | +In order to interact with the Azure Queue service, you'll need to create an instance of a client, `QueueClient`. The [Azure Identity] library makes it easy to add Microsoft Entra ID support for authenticating Azure SDK clients with their corresponding Azure services: |
| 40 | + |
| 41 | +```rust no_run |
| 42 | +use azure_storage_queue::clients::{QueueClient, QueueClientOptions}; |
| 43 | +use azure_identity::DefaultAzureCredential; |
| 44 | + |
| 45 | +#[tokio::main] |
| 46 | +async fn main() -> Result<(), Box<dyn std::error::Error>> { |
| 47 | + // Create a QueueClient that will authenticate through Microsoft Entra ID |
| 48 | + let credential = DefaultAzureCredential::new()?; |
| 49 | + let queue_client = QueueClient::new( |
| 50 | + "https://<storage_account_name>.blob.core.windows.net/", // endpoint |
| 51 | + "queue-name", // queue name |
| 52 | + credential, // credential |
| 53 | + Some(QueueClientOptions::default()), // QueueClient options |
| 54 | + )?; |
| 55 | + Ok(()) |
| 56 | +} |
| 57 | +``` |
| 58 | + |
| 59 | +#### Permissions |
| 60 | + |
| 61 | +You may need to specify RBAC roles to access Queues via Microsoft Entra ID. Please see [Assign an Azure role for access to queue data] for more details. |
| 62 | + |
| 63 | +## Features |
| 64 | + |
| 65 | +The following methods are available on the ```QueueClient``` class: |
| 66 | + |
| 67 | +- ```new```: Create a new instance of the ```QueueClient```. |
| 68 | +- ```create```: Creates a new queue, will fail if the queue already exists. |
| 69 | +- ```create_if_not_exists```: Creates a new queue, will _not_ fail if the queue already exists. |
| 70 | +- ```delete```: Deletes a queue, will fail if the queue does not exist. |
| 71 | +- ```delete_if_exists```: Deletes a queue, will _not_ fail if the queue does not exist. |
| 72 | +- ```delete_message```: Deletes a single message from the queue. |
| 73 | +- ```delete_messages```: Deletes all the messages in a queue. Requires Account Owner permission or it will fail. |
| 74 | +- ```exists```: Returns bool representing whether the queue exists or not. |
| 75 | +- ```get_metadata```: Returns metadata for the queue. |
| 76 | +- ```get_properties```: Returns the properties of the queue service. |
| 77 | +- ```peek_message```: Peeks a single message from the front of the queue without removing it. |
| 78 | +- ```peek_messages```: Peeks multiple messages from the front of the queue without removing them. |
| 79 | +- ```receive_message```: Receive a single message from the queue. |
| 80 | +- ```receive_messages```: Receive multiple messages from the queue. The number of messages to return is determined by the ```AzureQueueStorageMessagesOperationsClientDequeueOptions::number_of_messages``` property. |
| 81 | +- ```send_message```: Sends a message to the queue. |
| 82 | +- ```set_metadata```: Sets metadata on the queue. |
| 83 | +- ```update_message```: Updates a specific message in the queue. |
| 84 | + |
| 85 | +## Examples |
| 86 | + |
| 87 | +<!-- TODO: Update the link below when the PR is merged --> |
| 88 | +Executable examples of all the functions provided by this SDK can be found in the [queue_client.rs]<!--(https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_queue/examples/queue_client.rs)--> file in the examples directory. |
| 89 | + |
| 90 | +## Next steps |
| 91 | + |
| 92 | +### Provide feedback |
| 93 | + |
| 94 | +If you encounter bugs or have suggestions, [open an issue](https://github.com/Azure/azure-sdk-for-rust/issues). |
| 95 | + |
| 96 | +## Contributing |
| 97 | + |
| 98 | +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. For details, visit [https://cla.microsoft.com](https://cla.microsoft.com). |
| 99 | + |
| 100 | +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'll only need to do this once across all repos using our CLA. |
| 101 | + |
| 102 | +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. |
| 103 | + |
| 104 | +<!-- TODO: Update the links below when the crate is published --> |
| 105 | +<!-- LINKS --> |
| 106 | +[Azure subscription]: https://azure.microsoft.com/free/ |
| 107 | +[Azure storage account]: https://learn.microsoft.com/azure/storage/common/storage-account-overview |
| 108 | +[Azure Portal]: https://learn.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal |
| 109 | +[Azure PowerShell]: https://learn.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-powershell |
| 110 | +[Azure CLI]: https://learn.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-cli |
| 111 | +[cargo]: https://dev-doc.rust-lang.org/stable/cargo/commands/cargo.html |
| 112 | +[Azure Identity]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity |
| 113 | +<!--[API reference documentation]: https://docs.rs/crate/azure_storage_queue/latest--> |
| 114 | +<!--[Package (crates.io)]: https://crates.io/crates/azure_storage_queue--> |
| 115 | +[Source code]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_queue |
| 116 | +[REST API documentation]: https://learn.microsoft.com/rest/api/storageservices/blob-service-rest-api |
| 117 | +[Product documentation]: https://learn.microsoft.com/azure/storage/blobs/storage-blobs-overview |
| 118 | +[Assign an Azure role for access to queue data]: https://learn.microsoft.com/azure/storage/queues/assign-azure-role-data-access?tabs=portal |
0 commit comments