Azure Storage Blobs client library for C - version 12.19.0

++

Azure Blob Storage is Microsoft's object storage solution for the cloud. It is optimized for storing massive amounts of unstructured data, such as text, binary data, images, documents, streaming media, and application data.

Source code | Package (vcpkg) | API reference documentation | Product documentation | Samples

Getting started

Prerequisites

If you need to create a Storage account, you can use the Azure portal or the Azure CLI. When using the Azure CLI, replace <your-resource-group-name> and <your-storage-account-name> with your own values. Storage account names must be globally unique.

az login
az storage account create `
  --resource-group <your-resource-group-name> `
  --name <your-storage-account-name> `
  --sku Standard_LRS

Install the package

The easiest way to acquire the C++ SDK is with the vcpkg package manager and CMake. See the Azure SDK for C++ installation instructions for more information. The following commands use vcpkg in manifest mode.

Create a vcpkg manifest in the root of your project:

vcpkg new --application

Add Azure Storage Blobs and Azure Identity to the manifest:

vcpkg add port azure-storage-blobs-cpp azure-identity-cpp

Then add the following to your CMakeLists.txt file:

find_package(azure-identity-cpp CONFIG REQUIRED)
find_package(azure-storage-blobs-cpp CONFIG REQUIRED)

target_link_libraries(
  <your project name>
  PRIVATE
    Azure::azure-identity
    Azure::azure-storage-blobs)

Set CMAKE_TOOLCHAIN_FILE to the path to vcpkg.cmake before the project() statement in your CMakeLists.txt file:

set(CMAKE_TOOLCHAIN_FILE "vcpkg-root/scripts/buildsystems/vcpkg.cmake")

You can instead pass the path with the -DCMAKE_TOOLCHAIN_FILE argument when configuring CMake. For other ways to acquire and install the library, see the Azure C++ project setup samples.

Create and authenticate clients

BlobServiceClient operates on the Blob service at the Storage account level. From it, you can create a BlobContainerClient for container operations and specialized blob clients for block, append, and page blobs.

The following example uses DefaultAzureCredential, which supports multiple credential types and uses credentials from your development environment. After signing in with az login, set AZURE_STORAGE_ACCOUNT_URL to a URL such as https://<your-storage-account-name>.blob.core.windows.net.

#include <azure/identity.hpp>
#include <azure/storage/blobs.hpp>

#include <cstddef>
#include <cstdlib>
#include <iostream>
#include <memory>
#include <stdexcept>
#include <string>
#include <vector>

using namespace Azure::Storage::Blobs;

int main()
{
  const char* accountUrl = std::getenv("AZURE_STORAGE_ACCOUNT_URL");
  if (accountUrl == nullptr)
  {
    throw std::runtime_error("AZURE_STORAGE_ACCOUNT_URL is not set.");
  }

  auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();
  BlobServiceClient serviceClient(accountUrl, credential);

  BlobContainerClient containerClient
      = serviceClient.GetBlobContainerClient("sample-container");
  BlockBlobClient blockBlobClient = containerClient.GetBlockBlobClient("sample-blob");
}

For more information about credential selection and configuration, see DefaultAzureCredential.

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, 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, accessed through BlobServiceClient
  • A container in the Storage account, accessed through BlobContainerClient
  • A blob in a container, accessed through BlobClient or a specialized BlockBlobClient, AppendBlobClient, or PageBlobClient

Authentication

The library supports Microsoft Entra ID credentials, connection strings, shared key credentials, shared access signatures, and anonymous public access where enabled. Microsoft Entra ID with DefaultAzureCredential is recommended for getting started. See the samples for other authentication options.

Thread safety

All client instance methods are thread-safe and independent of each other (guideline). Reusing client instances is safe, even across threads.

Additional concepts

Replaceable HTTP transport adapter | Response model types | Long-running operations

Examples

The examples below use the clients created in Create and authenticate clients.

Upload a blob

Create the container if it does not exist, and then upload data to a block blob:

const std::string blobContent = "Hello Azure!";

containerClient.CreateIfNotExists();

std::vector<uint8_t> buffer(blobContent.begin(), blobContent.end());
blockBlobClient.UploadFrom(buffer.data(), buffer.size());

Download a blob

Download the blob into a buffer:

auto properties = blockBlobClient.GetProperties().Value;
std::vector<uint8_t> buffer(static_cast<std::size_t>(properties.BlobSize));

blockBlobClient.DownloadTo(buffer.data(), buffer.size());

List blobs

List the blobs in a container:

for (auto blobPage = containerClient.ListBlobs(); blobPage.HasPage();
     blobPage.MoveToNextPage())
{
  for (const auto& blob : blobPage.Blobs)
  {
    std::cout << "blob: " << blob.Name << std::endl;
  }
}

Troubleshooting

Blob service operations throw an Azure::Storage::StorageException on failure. The exception includes the HTTP status code, service error code, request ID, and other details that can help diagnose the failure. See the Blob service error codes for service-specific errors.

try
{
  containerClient.Delete();
}
catch (const Azure::Storage::StorageException& exception)
{
  if (exception.ErrorCode == "ContainerNotFound")
  {
    // The container has already been deleted.
  }
  else
  {
    throw;
  }
}

Next steps

The following samples demonstrate common Blob Storage scenarios:

Contributing

For details on contributing to this repository, see the contributing guide.

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 the Contributor License Agreement.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately. Follow the instructions provided by the bot. You only need to do this once across all repositories using the CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any questions or comments.

Reporting security issues and security bugs

Security issues and bugs should be reported privately to the Microsoft Security Response Center (MSRC) at secure@microsoft.com. You should receive a response within 24 hours. If you do not, follow up by email to confirm that your original message was received. For more information, including the MSRC PGP key, see the Security TechCenter.

License

Azure SDK for C++ is licensed under the MIT license.

  • Last updated on