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

  • Artykuł

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

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.

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

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.

Diagram of Blob Storage architecture

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

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.

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.

  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.

    A screenshot showing how to assign a role.

  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.

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.

    A screenshot showing how to find the storage account name.

    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ń.

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++