Používání úložiště BLOB z C++How to use Blob storage from C++

Tato příručka ukazuje, jak provádět běžné scénáře pomocí úložiště objektů BLOB v Azure.This guide demonstrates how to perform common scenarios using Azure Blob storage. Příklady ukazují, jak nahrát, vypsat, stáhnout a odstranit objekty blob.The examples show how to upload, list, download, and delete blobs. Ukázky jsou napsané v C++ a využívají klientskou knihovnu služby Azure Storage pro C++.The samples are written in C++ and use the Azure Storage Client Library for C++. Další informace o službě BLOB Storage najdete v tématu Úvod do úložiště objektů BLOB v Azure.To learn more about Blob storage, see Introduction to Azure Blob storage.

Poznámka

Tato příručka je určená pro klientskou knihovnu služby Azure Storage pro C++ verze 1.0.0 nebo novější.This guide targets the Azure Storage Client Library for C++ version 1.0.0 and above. Microsoft doporučuje používat nejnovější verzi klientské knihovny pro úložiště pro C++, která je dostupná přes NuGet nebo GitHub.Microsoft recommends using the latest version of the Storage Client Library for C++, available via NuGet or GitHub.

Vytvoření účtu úložiště AzureCreate an Azure storage account

Nejjednodušší způsob, jak vytvořit první účet úložiště Azure, je pomocí Azure Portal.The easiest way to create your first Azure storage account is by using the Azure portal. Další informace najdete v tématu Vytvoření účtu úložiště.To learn more, see Create a storage account.

Účet úložiště Azure můžete vytvořit také pomocí prostředí Azure PowerShell, rozhraní příkazového řádku Azure nebo pomocí poskytovatele prostředků služby Azure Storage pro .NET.You can also create an Azure storage account by using Azure PowerShell, Azure CLI, or the Azure Storage Resource Provider for .NET.

Pokud nechcete v Azure v tuto chvíli vytvářet účet úložiště, můžete použít taky emulátor úložiště Azurite ke spuštění a testování kódu v místním prostředí.If you prefer not to create a storage account in Azure at this time, you can also use the Azurite storage emulator to run and test your code in a local environment. Další informace najdete v tématu použití emulátoru Azurite pro vývoj místních Azure Storage.For more information, see Use the Azurite emulator for local Azure Storage development.

Vytvoření aplikace C++Create a C++ application

V této příručce budete používat funkce úložiště, které se dají spouštět v rámci aplikace v jazyce C++.In this guide, you will use storage features which can be run within a C++ application.

Abyste mohli pokračovat, musíte si nainstalovat klientskou knihovnu služby Azure Storage pro C++ a vytvořit ve svém předplatném účet úložiště Azure.To do so, you will need to install the Azure Storage Client Library for C++ and create an Azure storage account in your Azure subscription.

Klientskou knihovnu služby Azure Storage pro C++ můžete nainstalovat následujícími způsoby:To install the Azure Storage Client Library for C++, you can use the following methods:

.\vcpkg.exe install azure-storage-cpp

Můžete najít průvodce pro sestavení zdrojového kódu a exportovat ho do NuGet v souboru Readme .You can find a guide for how to build the source code and export to NuGet in the README file.

Konfigurace aplikace pro přístup k úložišti objektů BLOBConfigure your application to access Blob storage

Do horní části souboru C++ přidejte následující příkazy include, u kterých chcete používat rozhraní API služby Azure Storage pro přístup k objektům blob:Add the following include statements to the top of the C++ file where you want to use the Azure storage APIs to access blobs:

#include <was/storage_account.h>
#include <was/blob.h>
#include <cpprest/filestream.h>  
#include <cpprest/containerstream.h> 

Nastavení připojovacího řetězce úložiště AzureSetup an Azure storage connection string

Klient úložiště Azure používá připojovací řetězec úložiště k uložení koncových bodů a přihlašovacích údajů pro přístup ke službám správy dat.An Azure storage client uses a storage connection string to store endpoints and credentials for accessing data management services. Při spuštění v klientské aplikaci musíte zadat připojovací řetězec úložiště v následujícím formátu s použitím názvu účtu úložiště a přístupového klíče úložiště pro účet úložiště, který je uvedený v Azure Portal pro hodnoty account a AccountKey .When running in a client application, you must provide the storage connection string in the following format, using the name of your storage account and the storage access key for the storage account listed in the Azure portal for the AccountName and AccountKey values. Informace o účtech úložiště a přístupových klíčích najdete v tématu informace o Azure Storagech účtech.For information on storage accounts and access keys, see About Azure Storage Accounts. Tento příklad ukazuje deklaraci statického pole pro uložení připojovacího řetězce:This example shows how you can declare a static field to hold the connection string:

// Define the connection-string with your values.
const utility::string_t storage_connection_string(U("DefaultEndpointsProtocol=https;AccountName=your_storage_account;AccountKey=your_storage_account_key"));

K otestování aplikace na místním počítači s Windows můžete použít emulátor úložiště Azurite.To test your application in your local Windows computer, you can use the Azurite storage emulator. Azurite je nástroj, který simuluje služby objektů BLOB a front, které jsou dostupné v Azure, na vašem místním vývojovém počítači.Azurite is a utility that simulates the Blob and Queue services available in Azure on your local development machine. Následující příklad ukazuje deklaraci statického pole pro uložení připojovacího řetězce k místnímu emulátoru úložiště:The following example shows how you can declare a static field to hold the connection string to your local storage emulator:

// Define the connection-string with Azurite.
const utility::string_t storage_connection_string(U("UseDevelopmentStorage=true;"));

Pokud chcete začít Azurite, přečtěte si téma použití emulátoru Azurite pro vývoj místních Azure Storage.To start Azurite, see Use the Azurite emulator for local Azure Storage development.

V následujících ukázkách se předpokládá, že jste pomocí některé z těchto dvou metod získali připojovací řetězec úložiště.The following samples assume that you have used one of these two methods to get the storage connection string.

Načtení účtu úložištěRetrieve your storage account

K reprezentaci informací o účtu úložiště můžete použít třídu cloud_storage_account .You can use the cloud_storage_account class to represent your Storage Account information. K načtení informací o vašem účtu úložiště z připojovacího řetězce úložiště můžete použít metodu parse.To retrieve your storage account information from the storage connection string, you can use the parse method.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

Dále získáte odkaz na třídu cloud_blob_client , protože umožňuje načíst objekty, které reprezentují kontejnery a objekty blob uložené v úložišti objektů BLOB.Next, get a reference to a cloud_blob_client class as it allows you to retrieve objects that represent containers and blobs stored within Blob storage. Následující kód vytvoří objekt cloud_blob_client pomocí objektu účtu úložiště, který jsme získali výše:The following code creates a cloud_blob_client object using the storage account object we retrieved above:

// Create the blob client.
azure::storage::cloud_blob_client blob_client = storage_account.create_cloud_blob_client();  

Postupy: vytvoření kontejneruHow to: Create a container

Každý objekt blob v úložišti Azure se musí nacházet v kontejneru.Every blob in Azure storage must reside in a container. Kontejner je součástí názvu objektu blob.The container forms part of the blob name. Třeba mycontainer je název kontejneru v těchto identifikátorech URI ukázkových objektů blob:For example, mycontainer is the name of the container in these sample blob URIs:

https://storagesample.blob.core.windows.net/mycontainer/blob1.txt
https://storagesample.blob.core.windows.net/mycontainer/photos/myphoto.jpg

Název kontejneru musí být platný název DNS, který odpovídá následujícím pravidlům pro pojmenování:A container name must be a valid DNS name, conforming to the following naming rules:

  1. Názvy kontejnerů musí začínat písmenem nebo číslicí a smí obsahovat jenom písmena, číslice a pomlčky (-).Container names must start with a letter or number, and can contain only letters, numbers, and the dash (-) character.
  2. Bezprostředně před a za každým znakem pomlčky (-) se musí nacházet písmeno nebo číslice. Názvy kontejnerů nesmí obsahovat po sobě jdoucí pomlčky.Every dash (-) character must be immediately preceded and followed by a letter or number; consecutive dashes are not permitted in container names.
  3. Název kontejneru musí být psaný malými písmeny.All letters in a container name must be lowercase.
  4. Názvy kontejnerů musí mít délku 3 až 63 znaků.Container names must be from 3 through 63 characters long.

Důležité

Upozorňujeme, že název kontejneru musí být psaný malými písmeny.Note that the name of a container must always be lowercase. Pokud v názvu kontejneru napíšete velké písmeno nebo jinak porušíte pravidla po pojmenování kontejnerů, může se zobrazit chyba 400 (Chybný požadavek).If you include an upper-case letter in a container name, or otherwise violate the container naming rules, you may receive a 400 error (Bad Request).

Tento příklad ukazuje, jak vytvořit kontejner, pokud ještě neexistuje:This example shows how to create a container if it does not already exist:

try
{
    // Retrieve storage account from connection string.
    azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

    // Create the blob client.
    azure::storage::cloud_blob_client blob_client = storage_account.create_cloud_blob_client();

    // Retrieve a reference to a container.
    azure::storage::cloud_blob_container container = blob_client.get_container_reference(U("my-sample-container"));

    // Create the container if it doesn't already exist.
    container.create_if_not_exists();
}
catch (const std::exception& e)
{
    std::wcout << U("Error: ") << e.what() << std::endl;
}  

Ve výchozím nastavení je nový kontejner privátní a musíte zadat přístupový klíč k úložišti pro stahování objektů BLOB z tohoto kontejneru.By default, the new container is private and you must specify your storage access key to download blobs from this container. Pokud chcete, aby byly soubory (objekty BLOB) v kontejneru dostupné všem uživatelům, můžete nastavit, aby byl kontejner veřejný, a to pomocí následujícího kódu:If you want to make the files (blobs) within the container available to everyone, you can set the container to be public using the following code:

// Make the blob container publicly accessible.
azure::storage::blob_container_permissions permissions;
permissions.set_public_access(azure::storage::blob_container_public_access_type::blob);
container.upload_permissions(permissions);  

Kdokoli na internetu může vidět objekty blob ve veřejném kontejneru, ale můžete je upravit nebo odstranit jenom v případě, že máte příslušný přístupový klíč.Anyone on the Internet can see blobs in a public container, but you can modify or delete them only if you have the appropriate access key.

Postupy: nahrání objektu blob do kontejneruHow to: Upload a blob into a container

Úložiště objektů BLOB v Azure podporuje objekty blob bloku a objekty blob stránky.Azure Blob storage supports block blobs and page blobs. Ve většině případů se jako vhodný typ k použití doporučuje objekt blob bloku.In the majority of cases, block blob is the recommended type to use.

Když chcete nahrát soubor do objektu blob bloku, získejte odkaz na kontejner a použijte ho k získání odkazu objektu blob bloku.To upload a file to a block blob, get a container reference and use it to get a block blob reference. Jakmile budete mít odkaz na objekt blob, můžete do něj nahrát libovolný datový proud zavoláním metody upload_from_stream .Once you have a blob reference, you can upload any stream of data to it by calling the upload_from_stream method. Tahle operace vytvoří objekt blob, pokud už dříve neexistoval, nebo ho přepíše, pokud už existoval.This operation will create the blob if it didn't previously exist, or overwrite it if it does exist. Následující příklad ukazuje, jak nahrát objekt blob do kontejneru, zároveň předpokládá, že kontejner byl již vytvořen.The following example shows how to upload a blob into a container and assumes that the container was already created.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the blob client.
azure::storage::cloud_blob_client blob_client = storage_account.create_cloud_blob_client();

// Retrieve a reference to a previously created container.
azure::storage::cloud_blob_container container = blob_client.get_container_reference(U("my-sample-container"));

// Retrieve reference to a blob named "my-blob-1".
azure::storage::cloud_block_blob blockBlob = container.get_block_blob_reference(U("my-blob-1"));

// Create or overwrite the "my-blob-1" blob with contents from a local file.
concurrency::streams::istream input_stream = concurrency::streams::file_stream<uint8_t>::open_istream(U("DataFile.txt")).get();
blockBlob.upload_from_stream(input_stream);
input_stream.close().wait();

// Create or overwrite the "my-blob-2" and "my-blob-3" blobs with contents from text.
// Retrieve a reference to a blob named "my-blob-2".
azure::storage::cloud_block_blob blob2 = container.get_block_blob_reference(U("my-blob-2"));
blob2.upload_text(U("more text"));

// Retrieve a reference to a blob named "my-blob-3".
azure::storage::cloud_block_blob blob3 = container.get_block_blob_reference(U("my-directory/my-sub-directory/my-blob-3"));
blob3.upload_text(U("other text"));  

Alternativně můžete použít metodu upload_from_file pro nahrání souboru do objektu blob bloku.Alternatively, you can use the upload_from_file method to upload a file to a block blob.

Postupy: výpis objektů BLOB v kontejneruHow to: List the blobs in a container

Pokud chcete mít seznam objektů blob v kontejneru, nejdřív získejte odkaz na kontejner.To list the blobs in a container, first get a container reference. Pak můžete použít metodu list_blobs kontejneru k načtení objektů BLOB a adresářů v ní.You can then use the container's list_blobs method to retrieve the blobs and/or directories within it. Chcete-li získat přístup k bohatě se sadou vlastností a metod vrácených list_blob_item, je nutné volat metodu list_blob_item. as _blob pro získání objektu cloud_blob nebo metody list_blob. as _directory pro získání objektu cloud_blob_directory.To access the rich set of properties and methods for a returned list_blob_item, you must call the list_blob_item.as_blob method to get a cloud_blob object, or the list_blob.as_directory method to get a cloud_blob_directory object. Následující kód ukazuje, jak načíst a vystavit výstup identifikátoru URI každé položky v kontejneru My-Sample-Container :The following code demonstrates how to retrieve and output the URI of each item in the my-sample-container container:

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the blob client.
azure::storage::cloud_blob_client blob_client = storage_account.create_cloud_blob_client();

// Retrieve a reference to a previously created container.
azure::storage::cloud_blob_container container = blob_client.get_container_reference(U("my-sample-container"));

// Output URI of each item.
azure::storage::list_blob_item_iterator end_of_results;
for (auto it = container.list_blobs(); it != end_of_results; ++it)
{
    if (it->is_blob())
    {
        std::wcout << U("Blob: ") << it->as_blob().uri().primary_uri().to_string() << std::endl;
    }
    else
    {
        std::wcout << U("Directory: ") << it->as_directory().uri().primary_uri().to_string() << std::endl;
    }
}

Další informace o výpisu operací najdete v tématu seznam Azure Storage prostředků v jazyce C++.For more details on listing operations, see List Azure Storage Resources in C++.

Postupy: stahování objektů BLOBHow to: Download blobs

Chcete-li stáhnout objekty blob, načtěte nejprve odkaz na objekt BLOB a potom zavolejte metodu download_to_stream .To download blobs, first retrieve a blob reference and then call the download_to_stream method. Následující příklad používá metodu download_to_stream k přenosu obsahu objektu blob do objektu streamu, který pak můžete zachovat do místního souboru.The following example uses the download_to_stream method to transfer the blob contents to a stream object that you can then persist to a local file.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the blob client.
azure::storage::cloud_blob_client blob_client = storage_account.create_cloud_blob_client();

// Retrieve a reference to a previously created container.
azure::storage::cloud_blob_container container = blob_client.get_container_reference(U("my-sample-container"));

// Retrieve reference to a blob named "my-blob-1".
azure::storage::cloud_block_blob blockBlob = container.get_block_blob_reference(U("my-blob-1"));

// Save blob contents to a file.
concurrency::streams::container_buffer<std::vector<uint8_t>> buffer;
concurrency::streams::ostream output_stream(buffer);
blockBlob.download_to_stream(output_stream);

std::ofstream outfile("DownloadBlobFile.txt", std::ofstream::binary);
std::vector<unsigned char>& data = buffer.collection();

outfile.write((char *)&data[0], buffer.size());
outfile.close();  

Alternativně můžete pomocí metody download_to_file stáhnout obsah objektu blob do souboru.Alternatively, you can use the download_to_file method to download the contents of a blob to a file. Kromě toho můžete také pomocí metody download_text stáhnout obsah objektu BLOB jako textový řetězec.In addition, you can also use the download_text method to download the contents of a blob as a text string.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the blob client.
azure::storage::cloud_blob_client blob_client = storage_account.create_cloud_blob_client();

// Retrieve a reference to a previously created container.
azure::storage::cloud_blob_container container = blob_client.get_container_reference(U("my-sample-container"));

// Retrieve reference to a blob named "my-blob-2".
azure::storage::cloud_block_blob text_blob = container.get_block_blob_reference(U("my-blob-2"));

// Download the contents of a blog as a text string.
utility::string_t text = text_blob.download_text();

Postupy: odstranění objektů BLOBHow to: Delete blobs

Pokud chcete odstranit objekt blob, nejdřív Získejte odkaz na objekt BLOB a pak na něj volejte metodu delete_blob .To delete a blob, first get a blob reference and then call the delete_blob method on it.

// Retrieve storage account from connection string.
azure::storage::cloud_storage_account storage_account = azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the blob client.
azure::storage::cloud_blob_client blob_client = storage_account.create_cloud_blob_client();

// Retrieve a reference to a previously created container.
azure::storage::cloud_blob_container container = blob_client.get_container_reference(U("my-sample-container"));

// Retrieve reference to a blob named "my-blob-1".
azure::storage::cloud_block_blob blockBlob = container.get_block_blob_reference(U("my-blob-1"));

// Delete the blob.
blockBlob.delete_blob();

Další krokyNext steps

Teď, když jste se naučili základy služby Blob Storage, můžete získat další informace o Azure Storage pomocí těchto odkazů.Now that you've learned the basics of blob storage, follow these links to learn more about Azure Storage.