From c84a2a974f6757f3b7e836323d7d9cc71f0bf5b7 Mon Sep 17 00:00:00 2001 From: JinmingHu Date: Fri, 3 Feb 2023 13:50:28 +0800 Subject: [PATCH] update storage README (#4183) --- sdk/storage/README.md | 150 +++------------ sdk/storage/azure-storage-blobs/README.md | 176 ++++++++++++++++++ sdk/storage/azure-storage-common/README.md | 84 +++++++++ .../azure-storage-files-datalake/README.md | 3 + .../azure-storage-files-shares/README.md | 3 + sdk/storage/azure-storage-queues/README.md | 3 + 6 files changed, 292 insertions(+), 127 deletions(-) create mode 100644 sdk/storage/azure-storage-blobs/README.md create mode 100644 sdk/storage/azure-storage-common/README.md create mode 100644 sdk/storage/azure-storage-files-datalake/README.md create mode 100644 sdk/storage/azure-storage-files-shares/README.md create mode 100644 sdk/storage/azure-storage-queues/README.md diff --git a/sdk/storage/README.md b/sdk/storage/README.md index f56b93153..795f31a6c 100644 --- a/sdk/storage/README.md +++ b/sdk/storage/README.md @@ -1,139 +1,35 @@ -# Azure Storage Client Library for C++ +# Azure Storage libraries for C++ -The Azure Storage Client Library for C++ allows you to build applications against Microsoft Azure Storage. For an overview of Azure Storage, see [Introduction to Microsoft Azure Storage](https://docs.microsoft.com/azure/storage/common/storage-introduction). +Azure Storage is a Microsoft-managed service providing cloud storage that is highly available, secure, durable, scalable, and redundant. Azure Storage includes Blobs (objects), Queues, and Files. -# Features +- [Azure.Storage.Blobs](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-blobs/README.md) is Microsoft's object storage solution for the cloud. Blob storage is optimized for storing massive amounts of unstructured data that does not adhere to a particular data model or definition, such as text or binary data. -- Blobs - - Create/Delete/List Containers - - Create/Read/Update/Delete/List Blobs -- DataLake Gen 2 - - Create/Delete File Systems - - Create/Delete Directories - - Create/Read/Append/Flush/Delete Files -- File Shares - - Create/Delete Shares - - Create/Delete Directories - - Create/Read/Delete Files +- [Azure.Storage.Queues](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-queues/README.md) is a service for storing large numbers of messages. A queue message can be up to 64 KB in size and a queue may contain millions of messages, up to the total capacity limit of a storage account. -# Getting started +- [Azure.Storage.Files.Shares](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-files-shares/README.md) offers fully managed file shares in the cloud that are accessible via the industry standard Server Message Block (SMB) protocol. Azure file shares can be mounted concurrently by cloud or on-premises deployments of Windows, Linux, and macOS. -For the best development experience, we recommend that developers use the [CMake projects in Visual Studio](https://docs.microsoft.com/cpp/build/cmake-projects-in-visual-studio?view=vs-2019) to view and build the source code together with its dependencies. +- [Azure.Storage.Files.DataLake](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-files-datalake/README.md) includes all the capabilities required to make it easy for developers, data scientists, and analysts to store data of any size, shape, and speed, and do all types of processing and analytics across platforms and languages. -## Requirements +- [Azure.Storage.Common](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-common/README.md) provides infrastructure shared by the other Azure Storage client libraries like shared key authentication and exceptions. -To call Azure services, you must first have an Azure subscription. Sign up for a [free trial](https://azure.microsoft.com/pricing/free-trial/) or use your [MSDN subscriber benefits](https://azure.microsoft.com/pricing/member-offers/msdn-benefits-details/). +## Contributing -## Need Help? +See the [Storage CONTRIBUTING.md][storage_contrib] for details on building, +testing, and contributing to these libraries. -Be sure to check out the [Azure Storage Forum](https://social.msdn.microsoft.com/Forums/azure/home?forum=windowsazuredata) on MSDN if you need help, or use [StackOverflow](https://stackoverflow.com/questions/tagged/azure). +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 [cla.microsoft.com][cla]. -## Collaborate & Contribute - -We gladly accept community contributions. - -- **Issues:** Report bugs on the [Issues page](https://github.com/Azure/azure-sdk-for-cpp/issues) in GitHub. Ideally, please add an "[Storage]" prefix to the title for easier categorizing. -- **Forums:** Communicate with the Azure Storage development team on the [Azure Storage Forum](https://social.msdn.microsoft.com/Forums/azure/home?forum=windowsazuredata) or [StackOverflow](https://stackoverflow.com/questions/tagged/azure). -- **Source Code Contributions:** Please follow the [contribution guidelines for Azure open source](https://azure.github.io/azure-sdk/cpp_introduction.html) for instructions about contributing to the source project. - -For general suggestions about Azure, use our [Azure feedback forum](https://feedback.azure.com/forums/34192--general-feedback). - -## Download & Install - -### Install Dependencies - -#### Windows - -On Windows, dependencies are managed by [vcpkg](https://github.com/microsoft/vcpkg). You can reference the [Quick Start](https://github.com/microsoft/vcpkg#quick-start-windows) to quickly set yourself up. -After Vcpkg is initialized and bootstrapped, you can install the dependencies: -```BatchFile -vcpkg.exe install curl:x64-windows-static -``` - -#### POSIX Platforms - -You can use the package manager on different POSIX platforms to install the dependencies. The dependencies to be installed are: - - - CMake 3.13.0 or higher. - - libxml2. - - OpenSSL. - - libcurl. - -### Build from Source - -First, download the repository to your local folder: -```BatchFile -git clone https://github.com/Azure/azure-sdk-for-cpp.git -``` - -#### Windows - -##### Use CMake to generate the solution file - -In a new folder you created under the root directory: -```BatchFile -cmake .. -A x64 -DCMAKE_TOOLCHAIN_FILE=/scripts/buildsystems/vcpkg.cmake -cmake --build . -``` - -The built library will be in `.\sdk\\\` respectively for Azure Core and Azure Storage. e.g. `azure_core.lib` will be in `.\sdk\core\azure-core\Debug` for debug configuration. - -##### Use Visual Studio's Open by folder feature -Open the root folder of the library with Visual Studio's Open folder feature. - -If Vcpkg is not globally integrated, then you need to open CMakeSettings.json and change the `Make toolchain file to be /scripts/buildsystems/vcpkg.cmake` and save. -Then you can build Azure Storage libraries by selecting the target in Visual Studio, or simply build all. -The libraries will be in `\out\build\\sdk\` respectively. - -#### POSIX Platforms - -You can run the following command in a new folder created under the downloaded code's root folder to build the code. - -```bash -cmake .. -DCMAKE_BUILD_TYPE=Debug -cmake --build . -``` -Then you can consume the built library with the header files. -make/ninja install is work in progress. - - -### Via NuGet -WIP -TODO when ready. - -### Via vcpkg -The easiest way to acquire the C++ SDK is leveraging vcpkg package manager. See the corresponding [Azure SDK for C++ readme section][azsdk_vcpkg_install]. - -To install Azure Storage packages via vcpkg: - -```cmd -> vcpkg install azure-storage-blobs-cpp azure-storage-files-datalake-cpp azure-storage-files-shares-cpp -``` - -Then, use in your CMake file: - -```CMake -find_package(azure-storage-blobs-cpp CONFIG REQUIRED) -target_link_libraries( PRIVATE Azure::azure-storage-blobs) - -find_package(azure-storage-files-datalake-cpp CONFIG REQUIRED) -target_link_libraries( PRIVATE Azure::azure-storage-files-datalake) - -find_package(azure-storage-files-shares-cpp CONFIG REQUIRED) -target_link_libraries( PRIVATE Azure::azure-storage-files-shares) -``` - -## Dependencies - - - [Azure Core SDK](https://github.com/Azure/azure-sdk-for-cpp/blob/main/README.md) - - libxml2 - -## Code Samples - -To get started with the coding, please visit the following code samples: -- [How to use Blob Storage from C++](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-blobs/samples/blob_getting_started.cpp) -- [How to use DataLake Gen 2 Storage from C++](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-files-datalake/samples/datalake_getting_started.cpp) -- [How to use File Storage from C++](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-files-shares/samples/file_share_getting_started.cpp) +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. +For more information see the [Code of Conduct FAQ][coc_faq] +or contact [opencode@microsoft.com][coc_contact] with any +additional questions or comments. -[azsdk_vcpkg_install]: https://github.com/Azure/azure-sdk-for-cpp#download--install-the-sdk +[storage_contrib]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md +[cla]: https://cla.microsoft.com +[coc]: https://opensource.microsoft.com/codeofconduct/ +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ +[coc_contact]: mailto:opencode@microsoft.com \ No newline at end of file diff --git a/sdk/storage/azure-storage-blobs/README.md b/sdk/storage/azure-storage-blobs/README.md new file mode 100644 index 000000000..093efd534 --- /dev/null +++ b/sdk/storage/azure-storage-blobs/README.md @@ -0,0 +1,176 @@ +# Azure Storage Blobs Client Library for C++ + +Azure Blob storage is Microsoft's object storage solution for the cloud. Blob storage is optimized for storing massive amounts of unstructured data. Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data. + +## Getting started + +### Install the package + +The easiest way to acquire the C++ SDK is leveraging vcpkg package manager. See the corresponding [Azure SDK for C++ readme section][azsdk_vcpkg_install]. + +To install Azure Storage packages via vcpkg: + +```batch +vcpkg install azure-storage-blobs-cpp +``` + +Then, use in your CMake file: + +```CMake +find_package(azure-storage-blobs-cpp CONFIG REQUIRED) +target_link_libraries( PRIVATE Azure::azure-storage-blobs) +``` + +### Prerequisites + +You need an Azure subscription and a [Storage Account][storage_account_overview] to use this package. + +To create a new Storage Account, you can use the [Azure Portal][create_account_with_azure_portal], [Azure PowerShell][create_account_with_powershell], or the [Azure CLI][create_account_with_azure_cli]. + +### Build from Source + +First, download the repository to your local folder: + +```batch +git clone https://github.com/Azure/azure-sdk-for-cpp.git +``` + +Create a new folder under the root directory of local cloned repo, switch into this folder and run below commands: + +Windows: + +```batch +cmake .. -A x64 +cmake --build . --target azure-storage-blobs +``` + +or Unix: + +```batch +cmake .. -DCMAKE_BUILD_TYPE=Debug +cmake --build . --target azure-storage-blobs +``` + +## Key concepts + +Blob storage is designed for: + +- Serving images or documents directly to a browser. +- Storing files for distributed access. +- Streaming video and audio. +- Writing to log files. +- Storing data for backup and restore, disaster recovery, and archiving. +- Storing data for analysis by an on-premises or Azure-hosted service. + +Blob storage offers three types of resources: + +- The storage account used via `BlobServiceClient` +- A container in the storage account used via `BlobContainerClient` +- A blob in a container used via `BlobClient` + +Learn more about options for authentication (including Connection Strings, Shared Key, Shared Key Signatures, Active Directory, and anonymous public access) in our [samples](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/storage/azure-storage-blobs/samples). + +### Thread safety + +We guarantee that all client instance methods are thread-safe and independent of each other ([guideline](https://azure.github.io/azure-sdk/cpp_introduction.html#thread-safety)). This ensures that the recommendation of reusing client instances is always safe, even across threads. + +### Additional concepts + +Client Options | [Accessing the response](https://github.com/Azure/azure-sdk-for-cpp#response-t-model-types) | [Long-running operations](https://github.com/Azure/azure-sdk-for-cpp#long-running-operations) | Handling failures + +## Examples + +### Uploading a blob + +```C++ +const std::string connectionString = ""; +const std::string containerName = "sample-container"; +const std::string blobName = "sample-blob"; + +auto containerClient = BlobContainerClient::CreateFromConnectionString(connectionString, containerName); +containerClient.CreateIfNotExists(); + +BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName); +// upload from local file +blobClient.UploadFrom(localFilePath); +// or upload from memory buffer +blobClinet.UploadFrom(bufferPtr, bufferLength); +``` + +### Downloading a blob + +```C++ +// download to local file +blobClient.DownloadTo(localFilePath); +// or download to memory buffer +blobClinet.DownloadTo(bufferPtr, bufferLength); +``` + +### Enumerating blobs + +```C++ +for (auto blobPage = containerClient.ListBlobs(); blobPage.HasPage(); blobPage.MoveToNextPage()) { + for (auto& blob : blobPage.Blobs) { + // Below is what you want to do with each blob + std::cout << "blob: " << blob.Name << std::endl; + } +} +``` + +## Troubleshooting + +All Blob service operations will throw a [StorageException](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-common/inc/azure/storage/common/storage_exception.hpp) +on failure with helpful [ErrorCode](https://learn.microsoft.com/rest/api/storageservices/blob-service-error-codes)s. +Many of these errors are recoverable. + +```C++ +try +{ + containerClient.Delete(); +} +catch (Azure::Storage::StorageException& e) +{ + if (e.ErrorCode == "ContainerNotFound") + { + // ignore the error if the container does not exist. + } + else + { + // handle other errors here + } +} +``` + +## Next steps + +Get started with our [Blob samples](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/storage/azure-storage-blobs/samples): + +1. [Upload and download blobs](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-blobs/samples/blob_getting_started.cpp) +2. [List operations](https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/storage/azure-storage-blobs/samples/blob_list_operation.cpp) + +## Contributing + +See the [Storage CONTRIBUTING.md][storage_contrib] for details on building, +testing, and contributing to these libraries. + +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 [cla.microsoft.com][cla]. + +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. +For more information see the [Code of Conduct FAQ][coc_faq] +or contact [opencode@microsoft.com][coc_contact] with any +additional questions or comments. + + +[azsdk_vcpkg_install]: https://github.com/Azure/azure-sdk-for-cpp#download--install-the-sdk +[storage_account_overview]: https://learn.microsoft.com/azure/storage/common/storage-account-overview +[create_account_with_azure_portal]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-portal +[create_account_with_powershell]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-powershell +[create_account_with_azure_cli]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-cli +[storage_contrib]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md +[cla]: https://cla.microsoft.com +[coc]: https://opensource.microsoft.com/codeofconduct/ +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ +[coc_contact]: mailto:opencode@microsoft.com \ No newline at end of file diff --git a/sdk/storage/azure-storage-common/README.md b/sdk/storage/azure-storage-common/README.md new file mode 100644 index 000000000..62f777c62 --- /dev/null +++ b/sdk/storage/azure-storage-common/README.md @@ -0,0 +1,84 @@ +# Azure Storage Common Client Library for C++ + +Azure Storage is a Microsoft-managed service providing cloud storage that is highly available, secure, durable, scalable, and redundant. Azure Storage includes Azure Blobs (objects), Azure Data Lake Storage Gen2, Azure Files, and Azure Queues. +The Azure Storage Common library provides infrastructure shared by the other Azure Storage client libraries. + +## Getting Started + +### Install the package + +The easiest way to acquire the C++ SDK is leveraging vcpkg package manager. See the corresponding [Azure SDK for C++ readme section][azsdk_vcpkg_install]. + +To install Azure Storage packages via vcpkg: + +```batch +vcpkg install azure-storage-common-cpp +``` + +Then, use in your CMake file: + +```CMake +find_package(azure-storage-common-cpp CONFIG REQUIRED) +target_link_libraries( PRIVATE Azure::azure-storage-common) +``` + +### Prerequisites + +You need an Azure subscription and a [Storage Account][storage_account_overview] to use this package. + +To create a new Storage Account, you can use the [Azure Portal][create_account_with_azure_portal], [Azure PowerShell][create_account_with_powershell], or the [Azure CLI][create_account_with_azure_cli]. + +### Build from Source + +First, download the repository to your local folder: + +```batch +git clone https://github.com/Azure/azure-sdk-for-cpp.git +``` + +Create a new folder under the root directory of local cloned repo, switch into this folder and run below commands: + +Windows: + +```batch +cmake .. -A x64 +cmake --build . --target azure-storage-common +``` + +or Unix: + +```batch +cmake .. -DCMAKE_BUILD_TYPE=Debug +cmake --build . --target azure-storage-common +``` + +## Key concepts + +The Azure Storage Common client library contains shared infrastructure like authentication credentials and exception types. + +## Contributing + +See the [Storage CONTRIBUTING.md][storage_contrib] for details on building, +testing, and contributing to these libraries. + +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 [cla.microsoft.com][cla]. + +This project has adopted the [Microsoft Open Source Code of Conduct][coc]. +For more information see the [Code of Conduct FAQ][coc_faq] +or contact [opencode@microsoft.com][coc_contact] with any +additional questions or comments. + + +[azsdk_vcpkg_install]: https://github.com/Azure/azure-sdk-for-cpp#download--install-the-sdk +[storage_account_overview]: https://learn.microsoft.com/azure/storage/common/storage-account-overview +[create_account_with_azure_portal]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-portal +[create_account_with_powershell]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-powershell +[create_account_with_azure_cli]: https://learn.microsoft.com/azure/storage/common/storage-account-create?tabs=azure-cli +[storage_contrib]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/CONTRIBUTING.md +[cla]: https://cla.microsoft.com +[coc]: https://opensource.microsoft.com/codeofconduct/ +[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ +[coc_contact]: mailto:opencode@microsoft.com \ No newline at end of file diff --git a/sdk/storage/azure-storage-files-datalake/README.md b/sdk/storage/azure-storage-files-datalake/README.md new file mode 100644 index 000000000..9f27f243c --- /dev/null +++ b/sdk/storage/azure-storage-files-datalake/README.md @@ -0,0 +1,3 @@ +# Azure Storage Files Data Lake Client Library for C++ + +TBD \ No newline at end of file diff --git a/sdk/storage/azure-storage-files-shares/README.md b/sdk/storage/azure-storage-files-shares/README.md new file mode 100644 index 000000000..132813a57 --- /dev/null +++ b/sdk/storage/azure-storage-files-shares/README.md @@ -0,0 +1,3 @@ +# Azure Storage Files Shares Client Library for C++ + +TBD \ No newline at end of file diff --git a/sdk/storage/azure-storage-queues/README.md b/sdk/storage/azure-storage-queues/README.md new file mode 100644 index 000000000..205c62689 --- /dev/null +++ b/sdk/storage/azure-storage-queues/README.md @@ -0,0 +1,3 @@ +# Azure Storage Queues Client Library for C++ + +TBD \ No newline at end of file