Szybki start: biblioteka klienta usługi Azure Blob Storage dla języka C++

Wprowadzenie do biblioteki klienta usługi Azure Blob Storage dla języka C++. Azure Blob Storage to rozwiązanie magazynu obiektów firmy Microsoft dla chmury. Wykonaj następujące kroki, aby zainstalować pakiet i wypróbować przykładowy kod dla podstawowych zadań.

| Dokumentacja interfejsu API — przykłady | kodu | źródłowego biblioteki |

Wymagania wstępne

• Subskrypcja platformy Azure — utwórz jedną bezpłatnie
• Konto usługi Azure Storage — tworzenie konta magazynu
• Kompilator języka C++
• CMake
• vcpkg — menedżer pakietów C i C++

Konfigurowanie

W tej sekcji opisano proces przygotowywania projektu do pracy z biblioteką klienta usługi Azure Blob Storage dla języka C++. Najprostszym sposobem uzyskania zestawu Azure SDK dla języka C++ jest użycie vcpkg menedżera pakietów.

Instalowanie pakietów

vcpkg install Użyj polecenia , aby zainstalować bibliotekę usługi Azure Blob Storage dla języka C++ i niezbędne zależności:

vcpkg.exe install azure-storage-blobs-cpp

Biblioteka tożsamości platformy Azure jest wymagana w przypadku połączeń bez hasła z usługami platformy Azure:

vcpkg.exe install azure-identity-cpp

Aby uzyskać więcej informacji na temat konfigurowania projektu i pracy z zestawem Azure SDK dla języka C++, zobacz artykuł readme zestawu Azure SDK dla języka C++.

Tworzenie projektu

W programie Visual Studio utwórz nową aplikację konsolową języka C++ dla systemu Windows o nazwie BlobQuickstart.

Model obiektów

Usługa Azure Blob Storage jest zoptymalizowana pod kątem przechowywania ogromnych ilości danych bez struktury. Dane bez struktury są danymi, które nie są zgodne z żadnym modelem lub definicją danych, jak na przykład dane tekstowe lub binarne. Usługa Blob Storage oferuje trzy typy zasobów:

• Konto magazynu
• Kontener na koncie magazynu
• Obiekt blob w kontenerze

Na poniższym diagramie przedstawiono relacje między tymi zasobami.

Użyj tych klas języka C++, aby wchodzić w interakcje z tymi zasobami:

• BlobServiceClient: BlobServiceClient klasa umożliwia manipulowanie zasobami usługi Azure Storage i kontenerami obiektów blob.
• BlobContainerClient: BlobContainerClient klasa umożliwia manipulowanie kontenerami usługi Azure Storage i ich obiektami blob.
• BlobClient: BlobClient klasa umożliwia manipulowanie obiektami blob usługi Azure Storage. Jest to klasa bazowa dla wszystkich wyspecjalizowanych klas obiektów blob.
• BlockBlobClient: BlockBlobClient klasa umożliwia manipulowanie blokowymi obiektami blob usługi Azure Storage.

Przykłady kodu

Te przykładowe fragmenty kodu pokazują, jak wykonać następujące zadania za pomocą biblioteki klienta usługi Azure Blob Storage dla języka C++:

• Dodawanie plików dołączanych
• Uwierzytelnianie na platformie Azure i autoryzacja dostępu do danych obiektów blob
• Tworzenie kontenera
• Przekazywanie obiektów blob do kontenera
• Wyświetlanie listy obiektów blob w kontenerze
• Pobieranie obiektów blob
• Usuwanie kontenera

Dodawanie plików dołączanych

Z katalogu projektu:

1. Otwórz plik rozwiązania BlobQuickstart.sln w programie Visual Studio
2. W programie Visual Studio otwórz plik źródłowy BlobQuickstart.cpp
3. Usuń dowolny kod wewnątrz main , który został wygenerowany automatycznie
4. Dodawanie #include instrukcji i using namespace

#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;

Uwierzytelnianie na platformie Azure i autoryzacja dostępu do danych obiektów blob

Żądania aplikacji do usługi Azure Blob Storage muszą być autoryzowane. DefaultAzureCredential Użycie klasy udostępnionej przez bibliotekę klienta tożsamości platformy Azure jest zalecanym podejściem do implementowania połączeń bez hasła z usługami platformy Azure w kodzie, w tym usługi Blob Storage.

Możesz również autoryzować żądania do usługi Azure Blob Storage przy użyciu klucza dostępu do konta. Należy jednak zachować ostrożność przy użyciu tego podejścia. Deweloperzy muszą być sumienni, aby nigdy nie ujawniać klucza dostępu w niezabezpieczonej lokalizacji. Każdy, kto ma klucz dostępu, może autoryzować żądania względem konta magazynu i efektywnie ma dostęp do wszystkich danych. DefaultAzureCredential oferuje ulepszone korzyści związane z zarządzaniem i zabezpieczeniami za pośrednictwem klucza konta, aby umożliwić uwierzytelnianie bez hasła. Obie opcje przedstawiono w poniższym przykładzie.

Bez hasła (zalecane)

Biblioteka tożsamości platformy Azure zapewnia obsługę uwierzytelniania tokenów entra firmy Microsoft w zestawie Azure SDK. Udostępnia zestaw implementacji TokenCredential , które mogą służyć do konstruowania klientów zestawu Azure SDK, którzy obsługują uwierzytelnianie tokenów firmy Microsoft Entra. DefaultAzureCredential obsługuje wiele metod uwierzytelniania i określa, która metoda powinna być używana w czasie wykonywania.

Przypisywanie ról do konta użytkownika usługi Microsoft Entra

Podczas tworzenia aplikacji lokalnie upewnij się, że konto użytkownika, które uzyskuje dostęp do danych obiektów blob, ma odpowiednie uprawnienia. Będziesz potrzebować współautora danych obiektu blob usługi Storage, aby odczytywać i zapisywać dane obiektów blob. Aby przypisać sobie tę rolę, musisz przypisać rolę Administracja istratora dostępu użytkowników lub inną rolę obejmującą akcję Microsoft.Authorization/roleAssignments/write. Role RBAC platformy Azure można przypisać użytkownikowi przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell. Więcej informacji na temat dostępnych zakresów przypisań ról można znaleźć na stronie przeglądu zakresu.

W tym scenariuszu przypiszesz uprawnienia do konta użytkownika w zakresie konta magazynu, aby postępować zgodnie z zasadą najniższych uprawnień. Ta praktyka zapewnia użytkownikom tylko minimalne wymagane uprawnienia i tworzy bezpieczniejsze środowiska produkcyjne.

W poniższym przykładzie do konta użytkownika zostanie przypisana rola Współautor danych obiektu blob usługi Storage, która zapewnia zarówno dostęp do odczytu, jak i zapisu do danych obiektów blob na koncie magazynu.

Ważne

W większości przypadków propagacja przypisania roli na platformie Azure potrwa minutę lub dwie, ale w rzadkich przypadkach może upłynąć do ośmiu minut. Jeśli podczas pierwszego uruchomienia kodu wystąpią błędy uwierzytelniania, zaczekaj chwilę i spróbuj ponownie.

Witryna Azure Portal

1. W witrynie Azure Portal znajdź konto magazynu przy użyciu głównego paska wyszukiwania lub nawigacji po lewej stronie.

2. Na stronie przeglądu konta magazynu wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami) z menu po lewej stronie.

3. Na stronie Kontrola dostępu (Zarządzanie dostępem i tożsamościami) wybierz kartę Przypisania ról.

4. Wybierz pozycję + Dodaj z górnego menu, a następnie pozycję Dodaj przypisanie roli z wyświetlonego menu rozwijanego.

   

5. Użyj pola wyszukiwania, aby filtrować wyniki do żądanej roli. W tym przykładzie wyszukaj pozycję Współautor danych obiektu blob usługi Storage i wybierz pasujący wynik, a następnie wybierz pozycję Dalej.

6. W obszarze Przypisz dostęp do wybierz pozycję Użytkownik, grupa lub jednostka usługi, a następnie wybierz pozycję + Wybierz członków.

7. W oknie dialogowym wyszukaj nazwę użytkownika firmy Microsoft Entra (zazwyczaj adres e-mail user@domain ), a następnie wybierz pozycję Wybierz w dolnej części okna dialogowego.

8. Wybierz pozycję Przejrzyj i przypisz , aby przejść do ostatniej strony, a następnie ponownie przejrzyj i przypisz, aby ukończyć proces.

Interfejs wiersza polecenia platformy Azure

Aby przypisać rolę na poziomie zasobu przy użyciu interfejsu wiersza polecenia platformy Azure, należy najpierw pobrać identyfikator zasobu przy użyciu az storage account show polecenia . Właściwości wyjściowe można filtrować przy użyciu parametru --query .

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Skopiuj dane wyjściowe Id z poprzedniego polecenia. Następnie możesz przypisać role przy użyciu polecenia az role interfejsu wiersza polecenia platformy Azure.

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

Program PowerShell

Aby przypisać rolę na poziomie zasobu przy użyciu programu Azure PowerShell, należy najpierw pobrać identyfikator zasobu przy użyciu Get-AzResource polecenia .

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Id Skopiuj wartość z powyższych danych wyjściowych polecenia. Następnie można przypisać role przy użyciu polecenia New-AzRoleAssignment w programie PowerShell.

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

Zaloguj się i połącz kod aplikacji z platformą Azure przy użyciu opcji DefaultAzureCredential

Dostęp do danych na koncie magazynu można autoryzować, wykonując następujące czynności:

1. Upewnij się, że uwierzytelniasz się przy użyciu tego samego konta Microsoft Entra, do którego przypisano rolę na koncie magazynu. Możesz uwierzytelnić się za pomocą interfejsu wiersza polecenia platformy Azure. Zaloguj się do platformy Azure za pomocą interfejsu wiersza polecenia platformy Azure przy użyciu następującego polecenia:

   az login
   

2. Aby użyć polecenia DefaultAzureCredential, upewnij się, że zainstalowano pakiet azure-identity-cpp i dodano następujące elementy#include:

   #include <azure/identity/default_azure_credential.hpp>
   

3. Dodaj ten kod na końcu elementu main(). Gdy kod działa na lokalnej stacji roboczej, DefaultAzureCredential używa poświadczeń dewelopera dla interfejsu wiersza polecenia platformy Azure do uwierzytelniania na platformie 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. Pamiętaj, aby zaktualizować nazwę konta magazynu w identyfikatorze URI BlobServiceClient obiektu. Nazwę konta magazynu można znaleźć na stronie przeglądu witryny Azure Portal.

   

   Uwaga

   W przypadku korzystania z zestawu SDK języka C++ w środowisku produkcyjnym zaleca się włączenie tylko poświadczeń, które wiesz, że aplikacja będzie używana. Zamiast używać DefaultAzureCredentialpolecenia , należy autoryzować przy użyciu określonego typu poświadczeń lub przy użyciu ChainedTokenCredential obsługiwanych poświadczeń.

Parametry połączenia

Parametry połączenia zawiera klucz dostępu do konta magazynu i używa go do autoryzowania żądań. Zawsze należy zachować ostrożność, aby nigdy nie ujawniać kluczy w niezabezpieczonej lokalizacji.

Uwaga

Aby autoryzować dostęp do danych przy użyciu klucza dostępu do konta magazynu, musisz mieć uprawnienia do następującej akcji RBAC platformy Azure: Microsoft.Storage/storageAccounts/listkeys/action. Najmniej uprzywilejowana wbudowana rola z uprawnieniami dla tej akcji to Czytelnik i Dostęp do danych, ale każda rola obejmująca tę akcję będzie działać.

Witryna Azure Portal

1. Zaloguj się w witrynie Azure Portal.

2. Odszukaj konto magazynu.

3. W okienku menu konta magazynu w obszarze Zabezpieczenia i sieć wybierz pozycję Klucze dostępu. W tym miejscu możesz wyświetlić klucze dostępu do konta i kompletne parametry połączenia dla każdego klucza.

4. W okienku Klucze dostępu wybierz pozycję Pokaż klucze.

5. W sekcji key1 znajdź wartość ciągu Połączenie ion. Wybierz ikonę Kopiuj do schowka, aby skopiować parametry połączenia. W następnej sekcji dodasz wartość parametry połączenia do zmiennej środowiskowej.

   

Interfejs wiersza polecenia platformy Azure

Aby wyświetlić parametry połączenia dla konta magazynu, użyj polecenia az storage account show-connection-string.

az storage account show-connection-string --name "<your-storage-account-name>"

Program PowerShell

Za pomocą programu PowerShell można utworzyć parametry połączenia przy użyciu poleceń Get-AzStorageAccount i Get-AzStorageAccountKey.

$saName = "yourStorageAccountName"
$rgName = "yourResourceGroupName"
$sa = Get-AzStorageAccount -StorageAccountName $saName -ResourceGroupName $rgName

$saKey = (Get-AzStorageAccountKey -ResourceGroupName $rgName -Name $saName)[0].Value

'DefaultEndpointsProtocol=https;AccountName=' + $saName + ';AccountKey=' + $saKey + ';EndpointSuffix=core.windows.net'

Konfigurowanie parametrów połączenia magazynu

Po skopiowaniu parametry połączenia zapisz ją w nowej zmiennej środowiskowej na komputerze lokalnym z uruchomioną aplikacją. Aby ustawić zmienną środowiskową, otwórz okno konsoli i postępuj zgodnie z instrukcjami dla systemu operacyjnego. Zastąp <yourconnectionstring> element rzeczywistym parametry połączenia.

Windows:

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Po dodaniu zmiennej środowiskowej w systemie Windows należy uruchomić nowe wystąpienie okna poleceń.

Linux:

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Poniższy przykład kodu pobiera parametry połączenia dla konta magazynu z utworzonej wcześniej zmiennej środowiskowej i używa parametry połączenia do konstruowania obiektu klienta usługi.

Dodaj ten kod na końcu elementu main():

    // Retrieve the connection string for use with the application. The storage
    // connection string is stored in an environment variable on the machine
    // running the application called AZURE_STORAGE_CONNECTION_STRING.
    // Note that _MSC_VER is set when using MSVC compiler.
    static const char* AZURE_STORAGE_CONNECTION_STRING = "AZURE_STORAGE_CONNECTION_STRING";

#if !defined(_MSC_VER)
    const char* connectionString = std::getenv(AZURE_STORAGE_CONNECTION_STRING);
#else
	// Use getenv_s for MSVC
	size_t requiredSize;
	getenv_s(&requiredSize, NULL, NULL, AZURE_STORAGE_CONNECTION_STRING);
	if (requiredSize == 0) {
		throw std::runtime_error("missing connection string from env.");
	}
	std::vector<char> value(requiredSize);
	getenv_s(&requiredSize, value.data(), value.size(), AZURE_STORAGE_CONNECTION_STRING);
	std::string connectionStringStr = std::string(value.begin(), value.end());
	const char* connectionString = connectionStringStr.c_str();
#endif

	auto blobServiceClient = BlobServiceClient::CreateFromConnectionString(connectionString);

Ważne

Klucz dostępu do konta powinien być używany ostrożnie. Jeśli klucz dostępu do twojego konta zostanie utracony lub przypadkowo umieszczony w niezabezpieczonej lokalizacji, usługa może stać się podatna na zagrożenia. Każdy, kto ma klucz dostępu, może autoryzować żądania względem konta magazynu i efektywnie ma dostęp do wszystkich danych. DefaultAzureCredential zapewnia ulepszone funkcje zabezpieczeń i korzyści i jest zalecanym podejściem do zarządzania autoryzacją w usługach platformy Azure.

Tworzenie kontenera

Zdecyduj o nazwie nowego kontenera. Następnie utwórz wystąpienie BlobContainerClient i utwórz kontener.

Ważne

Nazwy kontenerów muszą być zapisane małymi literami. Aby uzyskać więcej informacji o nazewnictwie kontenerów i obiektów blob, zobacz temat Nazewnictwo i odwoływanie się do kontenerów, obiektów blob i metadanych.

Dodaj ten kod na końcu elementu 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();

Przekazywanie obiektów blob do kontenera

Poniższy fragment kodu:

1. Deklaruje ciąg zawierający ciąg "Hello Azure!"
2. Pobiera odwołanie do obiektu BlockBlobClient przez wywołanie elementu GetBlockBlobClient w kontenerze z sekcji Tworzenie kontenera.
3. Przekazuje ciąg do obiektu blob, wywołując funkcję UploadFrom . Ta funkcja tworzy obiekt blob, jeśli jeszcze nie istnieje, lub aktualizuje go, jeśli tak.

Dodaj ten kod na końcu elementu 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));

Wyświetlanie listy obiektów blob w kontenerze

Wyświetl listę obiektów blob w kontenerze, wywołując funkcję ListBlobs . Do kontenera dodano tylko jeden obiekt blob, więc operacja zwraca tylko ten obiekt blob.

Dodaj ten kod na końcu elementu main():

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

Pobieranie obiektów blob

Pobierz właściwości przekazanego obiektu blob. Następnie zadeklaruj i zmień rozmiar nowego std::vector<uint8_t> obiektu przy użyciu właściwości przekazanego obiektu blob. Pobierz utworzony wcześniej obiekt blob do nowego std::vector<uint8_t> obiektu, wywołując funkcję DownloadTo w klasie bazowej BlobClient . Na koniec wyświetl pobrane dane obiektu blob.

Dodaj ten kod na końcu elementu 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;

Usuwanie obiektu blob

Poniższy kod usuwa obiekt blob z kontenera usługi Azure Blob Storage przez wywołanie funkcji BlobClient.Delete .

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

Usuwanie kontenera

Poniższy kod czyści zasoby utworzone przez aplikację przez usunięcie całego kontenera przy użyciu obiektu BlobContainerClient.Usuń.

Dodaj ten kod na końcu elementu main():

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

Uruchamianie kodu

Ta aplikacja tworzy kontener i przekazuje plik tekstowy do usługi Azure Blob Storage. W tym przykładzie zostanie wyświetlona lista obiektów blob w kontenerze, pobranie pliku i wyświetlenie zawartości pliku. Na koniec aplikacja usuwa obiekt blob i kontener.

Dane wyjściowe aplikacji są podobne do następującego przykładu:

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

Następne kroki

W tym przewodniku Szybki start przedstawiono sposób przekazywania, pobierania i wyświetlania listy obiektów blob przy użyciu języka C++. Przedstawiono również sposób tworzenia i usuwania kontenera usługi Azure Blob Storage.

Aby wyświetlić przykład usługi Blob Storage w języku C++, przejdź do:

Biblioteka klienta usługi Azure Blob Storage dla przykładów języka C++