Snabbstart: Azure Blob Storage-klientbibliotek för C++

  • Artikel

Kom igång med Azure Blob Storage-klientbiblioteket för C++. Azure Blob Storage är Microsofts objektlagringslösning för molnet. Följ de här stegen för att installera paketet och prova exempelkod för grundläggande uppgifter.

| API-referensdokumentation Exempel på källkod | för bibliotek | |

Förutsättningar

Konfigurera

Det här avsnittet beskriver hur du förbereder ett projekt för att arbeta med Azure Blob Storage-klientbiblioteket för C++. Det enklaste sättet att hämta Azure SDK för C++ är att använda vcpkg pakethanteraren.

Installera paketen

vcpkg install Använd kommandot för att installera Azure Blob Storage-biblioteket för C++ och nödvändiga beroenden:

vcpkg.exe install azure-storage-blobs-cpp

Azure Identity-biblioteket behövs för lösenordslösa anslutningar till Azure-tjänster:

vcpkg.exe install azure-identity-cpp

Mer information om projektkonfiguration och arbete med Azure SDK för C++finns i Azure SDK för C++-läsning.

Skapa projektet

I Visual Studio skapar du ett nytt C++-konsolprogram för Windows med namnet BlobQuickstart.

Visual Studio dialog for configuring a new C++ Windows console app

Objektmodell

Azure Blob Storage är optimerat för lagring av enorma mängder ostrukturerade data. Ostrukturerade data är data som inte följer en viss datamodell eller definition, till exempel text eller binära data. Blob Storage erbjuder tre typer av resurser:

  • Lagringskontot
  • En container på lagringskontot
  • En blob i containern

Följande diagram visar relationen mellan de här resurserna.

Diagram of Blob Storage architecture

Använd dessa C++-klasser för att interagera med dessa resurser:

  • BlobServiceClient: Med BlobServiceClient klassen kan du ändra Azure Storage-resurser och blobcontainrar.
  • BlobContainerClient: Med BlobContainerClient klassen kan du manipulera Azure Storage-containrar och deras blobar.
  • BlobClient: Med BlobClient klassen kan du manipulera Azure Storage-blobar. Det är basklassen för alla specialiserade blobklasser.
  • BlockBlobClient: Med BlockBlobClient klassen kan du manipulera Azure Storage-blockblobar.

Kodexempel

Dessa exempelkodfragment visar hur du utför följande uppgifter med Azure Blob Storage-klientbiblioteket för C++:

Lägga till inkluderingsfiler

Från projektkatalogen:

  1. Öppna blobquickstart.sln-lösningsfilen i Visual Studio
  2. Öppna källfilen BlobQuickstart.cpp i Visual Studio
  3. Ta bort all kod inuti main som har genererats automatiskt
  4. Lägg till #include och using namespace instruktioner
#include <iostream>
#include <azure/core.hpp>
#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs.hpp>

using namespace Azure::Identity;
using namespace Azure::Storage::Blobs;

Autentisera till Azure och auktorisera åtkomst till blobdata

Programbegäranden till Azure Blob Storage måste vara auktoriserade. Att använda klassen DefaultAzureCredential som tillhandahålls av Azure Identity-klientbiblioteket är den rekommenderade metoden för att implementera lösenordslösa anslutningar till Azure-tjänster i din kod, inklusive Blob Storage.

Du kan också auktorisera begäranden till Azure Blob Storage med hjälp av kontoåtkomstnyckeln. Den här metoden bör dock användas med försiktighet. Utvecklare måste vara noggranna för att aldrig exponera åtkomstnyckeln på en osäker plats. Alla som har åtkomstnyckeln kan auktorisera begäranden mot lagringskontot och har effektivt åtkomst till alla data. DefaultAzureCredential ger bättre hanterings- och säkerhetsfördelar jämfört med kontonyckeln för att tillåta lösenordslös autentisering. Båda alternativen visas i följande exempel.

Azure Identity-biblioteket tillhandahåller stöd för Microsoft Entra-tokenautentisering i Hela Azure SDK. Den innehåller en uppsättning TokenCredential implementeringar som kan användas för att konstruera Azure SDK-klienter som stöder Microsoft Entra-tokenautentisering. DefaultAzureCredential stöder flera autentiseringsmetoder och avgör vilken metod som ska användas vid körning.

Tilldela roller till ditt Microsoft Entra-användarkonto

När du utvecklar lokalt kontrollerar du att användarkontot som har åtkomst till blobdata har rätt behörigheter. Du behöver Storage Blob Data-deltagare för att läsa och skriva blobdata. Om du vill tilldela dig själv den här rollen måste du tilldelas rollen Administratör för användaråtkomst eller en annan roll som innehåller åtgärden Microsoft.Authorization/roleAssignments/write . Du kan tilldela Azure RBAC-roller till en användare med hjälp av Azure-portalen, Azure CLI eller Azure PowerShell. Du kan lära dig mer om tillgängliga omfång för rolltilldelningar på översiktssidan för omfång .

I det här scenariot tilldelar du behörigheter till ditt användarkonto, begränsat till lagringskontot, för att följa principen om lägsta behörighet. Den här metoden ger användarna endast de minsta behörigheter som krävs och skapar säkrare produktionsmiljöer.

I följande exempel tilldelas rollen Storage Blob Data Contributor till ditt användarkonto, vilket ger både läs- och skrivåtkomst till blobdata i ditt lagringskonto.

Viktigt!

I de flesta fall tar det en minut eller två för rolltilldelningen att spridas i Azure, men i sällsynta fall kan det ta upp till åtta minuter. Om du får autentiseringsfel när du först kör koden väntar du en stund och försöker igen.

  1. Leta upp ditt lagringskonto i Azure-portalen med hjälp av huvudsökfältet eller det vänstra navigeringsfältet.

  2. På översiktssidan för lagringskontot väljer du Åtkomstkontroll (IAM) på den vänstra menyn.

  3. På sidan Åtkomstkontroll (IAM) väljer du fliken Rolltilldelningar .

  4. Välj + Lägg till på den översta menyn och sedan Lägg till rolltilldelning från den resulterande nedrullningsbara menyn.

    A screenshot showing how to assign a role.

  5. Använd sökrutan för att filtrera resultatet till önskad roll. I det här exemplet söker du efter Storage Blob Data Contributor och väljer matchande resultat och väljer sedan Nästa.

  6. Under Tilldela åtkomst till väljer du Användare, grupp eller tjänstens huvudnamn och sedan + Välj medlemmar.

  7. I dialogrutan söker du efter ditt Microsoft Entra-användarnamn (vanligtvis din user@domain e-postadress) och väljer sedan Välj längst ned i dialogrutan.

  8. Välj Granska + tilldela för att gå till den sista sidan och sedan Granska + tilldela igen för att slutföra processen.

Logga in och anslut din appkod till Azure med defaultAzureCredential

Du kan auktorisera åtkomst till data i ditt lagringskonto med hjälp av följande steg:

  1. Kontrollera att du är autentiserad med samma Microsoft Entra-konto som du tilldelade rollen till på ditt lagringskonto. Du kan autentisera via Azure CLI. Logga in på Azure via Azure CLI med följande kommando:

    az login

  2. Om du vill använda DefaultAzureCredentialkontrollerar du att azure-identity-cpp-paketet är installerat och att följande #include läggs till:

    #include <azure/identity/default_azure_credential.hpp>

  3. Lägg till den här koden i slutet av main(). När koden körs på din lokala arbetsstation DefaultAzureCredential använder du utvecklarautentiseringsuppgifterna för Azure CLI för att autentisera till Azure.

    // Initialize an instance of DefaultAzureCredential
 auto defaultAzureCredential = std::make_shared<DefaultAzureCredential>();

 auto accountURL = "https://<storage-account-name>.blob.core.windows.net";
 BlobServiceClient blobServiceClient(accountURL, defaultAzureCredential);

  4. Se till att uppdatera lagringskontots namn i objektets BlobServiceClient URI. Namnet på lagringskontot finns på översiktssidan i Azure-portalen.

    A screenshot showing how to find the storage account name.

    Kommentar

    När du använder C++ SDK i en produktionsmiljö rekommenderar vi att du bara aktiverar autentiseringsuppgifter som du vet att programmet kommer att använda. I stället för att använda DefaultAzureCredentialbör du auktorisera med en specifik typ av autentiseringsuppgifter eller med hjälp ChainedTokenCredential av autentiseringsuppgifter som stöds.

Skapa en container

Bestäm ett namn på den nya containern. Skapa sedan en instans av BlobContainerClient och skapa containern.

Viktigt!

Containernamn måste använda gemener. Mer information om namngivning av containrar och blobar finns i Namngivning och referens av containrar, blobar och metadata.

Lägg till den här koden i slutet av main():

std::string containerName = "myblobcontainer";
auto containerClient = blobServiceClient.GetBlobContainerClient("myblobcontainer");

// Create the container if it does not exist
std::cout << "Creating container: " << containerName << std::endl;
containerClient.CreateIfNotExists();

Ladda upp blobar till en container

Följande kodfragment:

  1. Deklarerar en sträng som innehåller "Hello Azure!"
  2. Hämtar en referens till ett BlockBlobClient-objekt genom att anropa GetBlockBlobClient på containern från avsnittet Skapa en container .
  3. Laddar upp strängen till bloben genom att anropa funktionen UploadFrom . Den här funktionen skapar bloben om den inte redan finns eller uppdaterar den om den gör det.

Lägg till den här koden i slutet av main():

std::string blobName = "blob.txt";
uint8_t blobContent[] = "Hello Azure!";
// Create the block blob client
BlockBlobClient blobClient = containerClient.GetBlockBlobClient(blobName);

// Upload the blob
std::cout << "Uploading blob: " << blobName << std::endl;
blobClient.UploadFrom(blobContent, sizeof(blobContent));

Visa blobar i en container

Lista blobarna i containern genom att anropa funktionen ListBlobs . Endast en blob har lagts till i containern, så åtgärden returnerar just den bloben.

Lägg till den här koden i slutet av main():

std::cout << "Listing blobs..." << std::endl;
auto listBlobsResponse = containerClient.ListBlobs();
for (auto blobItem : listBlobsResponse.Blobs)
{
    std::cout << "Blob name: " << blobItem.Name << std::endl;
}

Ladda ned blobbar

Hämta egenskaperna för den uppladdade bloben. Deklarera och ändra sedan storlek på ett nytt std::vector<uint8_t> objekt med hjälp av egenskaperna för den uppladdade bloben. Ladda ned den tidigare skapade bloben till det nya std::vector<uint8_t> objektet genom att anropa funktionen DownloadTo i basklassen BlobClient . Visa slutligen nedladdade blobdata.

Lägg till den här koden i slutet av main():

auto properties = blobClient.GetProperties().Value;
std::vector<uint8_t> downloadedBlob(properties.BlobSize);

blobClient.DownloadTo(downloadedBlob.data(), downloadedBlob.size());
std::cout << "Downloaded blob contents: " << std::string(downloadedBlob.begin(), downloadedBlob.end()) << std::endl;

Ta bort en blob

Följande kod tar bort bloben från Azure Blob Storage-containern genom att anropa funktionen BlobClient.Delete .

std::cout << "Deleting blob: " << blobName << std::endl;
blobClient.Delete();

Ta bort en container

Följande kod rensar de resurser som appen skapade genom att ta bort hela containern med hjälp av BlobContainerClient.Ta bort.

Lägg till den här koden i slutet av main():

std::cout << "Deleting container: " << containerName << std::endl;
containerClient.Delete();

Kör koden

Den här appen skapar en container och laddar upp en textfil till Azure Blob Storage. Exemplet visar sedan blobarna i containern, laddar ned filen och visar filinnehållet. Slutligen tar appen bort bloben och containern.

Utdata från appen liknar följande exempel:

Azure Blob Storage - C++ quickstart sample
Creating container: myblobcontainer
Uploading blob: blob.txt
Listing blobs...
Blob name: blob.txt
Downloaded blob contents: Hello Azure!
Deleting blob: blob.txt
Deleting container: myblobcontainer

Nästa steg

I den här snabbstarten har du lärt dig hur du laddar upp, laddar ned och listar blobar med C++. Du har också lärt dig hur du skapar och tar bort en Azure Blob Storage-container.

Om du vill se ett C++ Blob Storage-exempel fortsätter du till:

Azure Blob Storage-klientbibliotek för C++-exempel