Разработка приложений службы файлов Azure с помощью C++Develop for Azure Files with C++

Совет

Пробное использование обозревателя хранилищ Microsoft AzureTry the Microsoft Azure Storage Explorer

Обозреватель хранилищ Microsoft Azure — это бесплатное автономное приложение от корпорации Майкрософт, позволяющее визуализировать данные из службы хранилища Azure на платформе Windows, macOS и Linux.Microsoft Azure Storage Explorer is a free, standalone app from Microsoft that enables you to work visually with Azure Storage data on Windows, macOS, and Linux.

О данном учебникеAbout this tutorial

В рамках этого руководства вы узнаете, как выполнять основные операции в службе файлов Azure.In this tutorial, you'll learn how to perform basic operations on Azure Files. С помощью примеров на языке C++ вы узнаете, как создавать общие папки и каталоги, отправлять и удалять файлы, а также получать список файлов.Through samples written in C++, you'll learn how to create shares and directories, upload, list, and delete files. Если вы не знакомы со службой файлов Azure, мы предлагаем вам изучить понятия, описанные в последующих разделах. Это будет полезно для понимания примеров.If you are new to Azure Files, going through the concepts in the sections that follow will be helpful in understanding the samples.

  • Создание и удаление общих папок Azure.Create and delete Azure file shares
  • Создание и удаление каталогов.Create and delete directories
  • Перечисление файлов и каталогов в общей папке AzureEnumerate files and directories in an Azure file share
  • Передача, загрузка и удаление файлов.Upload, download, and delete a file
  • Установка квоты (максимального размера) для общей папки Azure.Set the quota (maximum size) for an Azure file share
  • Создайте подпись общего доступа (ключ SAS) для файла, который использует политику общего доступа, определенную в общей папке.Create a shared access signature (SAS key) for a file that uses a shared access policy defined on the share.

Примечание

Так как к службе файлов Azure можно обращаться через SMB, вы можете создавать простые приложения, которые получают доступ к общей папке Azure с использованием стандартных классов и функций ввода-вывода в C++.Because Azure Files may be accessed over SMB, it is possible to write simple applications that access the Azure file share using the standard C++ I/O classes and functions. Из этой статьи вы узнаете, как создавать приложения, использующие пакет SDK C++ для службы хранилища Azure, который использует REST API службы файлов для взаимодействия со службой файлов Azure.This article will describe how to write applications that use the Azure Storage C++ SDK, which uses the File REST API to talk to Azure Files.

Создание приложения на C++Create a C++ application

Для создания примеров необходимо установить клиентскую библиотеку хранилища Azure версии 2.4.0 для C++.To build the samples, you will need to install the Azure Storage Client Library 2.4.0 for C++. Вам также необходимо создать учетную запись хранилища Azure.You should also have created an Azure storage account.

Чтобы установить клиентскую библиотеку хранилища Azure версии 2.4.0 для C++, можно использовать следующие методы:To install the Azure Storage Client 2.4.0 for C++, you can use one of the following methods:

Install-Package wastorage

Настройка приложения для работы со службой файлов AzureSet up your application to use Azure Files

Добавьте следующие инструкции include в начало исходного файла C++, в котором вам нужен доступ к службе файлов Azure:Add the following include statements to the top of the C++ source file where you want to manipulate Azure Files:

#include <was/storage_account.h>
#include <was/file.h>

Настройка строки подключения к хранилищу AzureSet up an Azure storage connection string

Чтобы начать работу с хранилищем файлов, необходимо подключиться к вашей учетной записи хранилища Azure.To use File storage, you need to connect to your Azure storage account. Для начала потребуется настроить строку подключения, которая будет использоваться для подключения к учетной записи хранения.The first step would be to configure a connection string, which we'll use to connect to your storage account. Для этого определим статическую переменную.Let's define a static variable to do that.

// 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"));

Подключение к учетной записи хранилища AzureConnecting to an Azure storage account

Информацию о своей учетной записи хранения можно представить с помощью класса cloud_storage_account.You can use the cloud_storage_account class to represent your Storage Account information. Чтобы получить данные учетной записи хранения из строки подключения хранилища, можно использовать метод синтаксического анализа .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);

Создание файлового ресурса AzureCreate an Azure file share

Все файлы и каталоги в службе файлов Azure находятся в контейнере, который называется общей папкой.All files and directories in an Azure file share reside in a container called a Share. Учетная запись хранения может иметь столько общих папок, насколько позволяет емкость вашей учетной записи.Your storage account can have as many shares as your account capacity allows. Чтобы получить доступ к общей папке и ее содержимому, необходимо использовать клиент файлов Azure.To obtain access to a share and its contents, you need to use an Azure Files client.

// Create the Azure Files client.
azure::storage::cloud_file_client file_client =
  storage_account.create_cloud_file_client();

С его помощью вы получите ссылку на общую папку.Using the Azure Files client, you can then obtain a reference to a share.

// Get a reference to the file share
azure::storage::cloud_file_share share =
  file_client.get_share_reference(_XPLATSTR("my-sample-share"));

Чтобы создать общий ресурс, используйте метод create_if_not_exists объекта cloud_file_share.To create the share, use the create_if_not_exists method of the cloud_file_share object.

if (share.create_if_not_exists()) {
    std::wcout << U("New share created") << std::endl;
}

На этом этапе объект share содержит ссылку на общую папку с именем my-sample-share.At this point, share holds a reference to a share named my-sample-share.

Удаление общей папки AzureDelete an Azure file share

Удалить общую папку можно путем вызова метода delete_if_exists объекта cloud_file_share.Deleting a share is done by calling the delete_if_exists method on a cloud_file_share object. Ниже приведен пример кода, который выполняет это действие.Here's sample code that does that.

// Get a reference to the share.
azure::storage::cloud_file_share share =
  file_client.get_share_reference(_XPLATSTR("my-sample-share"));

// delete the share if exists
share.delete_share_if_exists();

Создание каталогаCreate a directory

Вы можете упорядочить файлы в хранилище, разместив их в подкаталогах, чтобы не захламлять корневой каталог.You can organize storage by putting files inside subdirectories instead of having all of them in the root directory. Служба файлов Azure позволяет создать такое количество каталогов, которое допускается в вашей учетной записи.Azure Files allows you to create as many directories as your account will allow. В следующем примере кода создается каталог с именем my-sample-directory в корневом каталоге, а также подкаталог my-sample-subdirectory.The code below will create a directory named my-sample-directory under the root directory as well as a subdirectory named my-sample-subdirectory.

// Retrieve a reference to a directory
azure::storage::cloud_file_directory directory = share.get_directory_reference(_XPLATSTR("my-sample-directory"));

// Return value is true if the share did not exist and was successfully created.
directory.create_if_not_exists();

// Create a subdirectory.
azure::storage::cloud_file_directory subdirectory =
  directory.get_subdirectory_reference(_XPLATSTR("my-sample-subdirectory"));
subdirectory.create_if_not_exists();

Удаление каталогаDelete a directory

Удаление каталога является простой задачей, однако следует отметить, что нельзя удалить каталог, по-прежнему содержащий файлы или другие каталоги.Deleting a directory is a simple task, although it should be noted that you cannot delete a directory that still contains files or other directories.

// Get a reference to the share.
azure::storage::cloud_file_share share =
  file_client.get_share_reference(_XPLATSTR("my-sample-share"));

// Get a reference to the directory.
azure::storage::cloud_file_directory directory =
  share.get_directory_reference(_XPLATSTR("my-sample-directory"));

// Get a reference to the subdirectory you want to delete.
azure::storage::cloud_file_directory sub_directory =
  directory.get_subdirectory_reference(_XPLATSTR("my-sample-subdirectory"));

// Delete the subdirectory and the sample directory.
sub_directory.delete_directory_if_exists();

directory.delete_directory_if_exists();

Перечисление файлов и каталогов в общей папке AzureEnumerate files and directories in an Azure file share

Получить список файлов и каталогов в общей папке довольно просто, вызвав метод list_files_and_directorie по ссылке cloud_file_directory.Obtaining a list of files and directories within a share is easily done by calling list_files_and_directories on a cloud_file_directory reference. Для доступа к широкому набору свойств и методов возвращаемого объекта list_file_and_directory_item необходимо вызвать метод list_file_and_directory_item.as_file, чтобы получить объект cloud_file, или метод list_file_and_directory_item.as_directory, чтобы получить объект cloud_file_directory.To access the rich set of properties and methods for a returned list_file_and_directory_item, you must call the list_file_and_directory_item.as_file method to get a cloud_file object, or the list_file_and_directory_item.as_directory method to get a cloud_file_directory object.

Следующий код демонстрирует, как получить и вывести URI каждого элемента в корневом каталоге общей папки.The following code demonstrates how to retrieve and output the URI of each item in the root directory of the share.

//Get a reference to the root directory for the share.
azure::storage::cloud_file_directory root_dir =
  share.get_root_directory_reference();

// Output URI of each item.
azure::storage::list_file_and_directory_result_iterator end_of_results;

for (auto it = directory.list_files_and_directories(); it != end_of_results; ++it)
{
    if(it->is_directory())
    {
        ucout << "Directory: " << it->as_directory().uri().primary_uri().to_string() << std::endl;
    }
    else if (it->is_file())
    {
        ucout << "File: " << it->as_file().uri().primary_uri().to_string() << std::endl;
    }
}

Отправка файлаUpload a file

Общая папка Azure содержит по меньшей мере один каталог для размещения файлов (корневой каталог).At the very least, an Azure file share contains a root directory where files can reside. В этом разделе вы узнаете, как отправить файл из локального хранилища в корневой каталог общего ресурса.In this section, you'll learn how to upload a file from local storage onto the root directory of a share.

Первым шагом при отправке файла является получение ссылки на каталог, где файл будет находиться.The first step in uploading a file is to obtain a reference to the directory where it should reside. Для этого нужно вызвать метод getRootDirectoryReference объекта общей папки.You do this by calling the get_root_directory_reference method of the share object.

//Get a reference to the root directory for the share.
azure::storage::cloud_file_directory root_dir = share.get_root_directory_reference();

Теперь, когда у вас имеется ссылка на корневой каталог общего ресурса, вы можете отправить туда файл.Now that you have a reference to the root directory of the share, you can upload a file onto it. В этом примере выполняется отправка из файла, текста и потока.This example uploads from a file, from text, and from a stream.

// Upload a file from a stream.
concurrency::streams::istream input_stream =
  concurrency::streams::file_stream<uint8_t>::open_istream(_XPLATSTR("DataFile.txt")).get();

azure::storage::cloud_file file1 =
  root_dir.get_file_reference(_XPLATSTR("my-sample-file-1"));
file1.upload_from_stream(input_stream);

// Upload some files from text.
azure::storage::cloud_file file2 =
  root_dir.get_file_reference(_XPLATSTR("my-sample-file-2"));
file2.upload_text(_XPLATSTR("more text"));

// Upload a file from a file.
azure::storage::cloud_file file4 =
  root_dir.get_file_reference(_XPLATSTR("my-sample-file-3"));
file4.upload_from_file(_XPLATSTR("DataFile.txt"));

Скачивание файлаDownload a file

Чтобы скачать файлы, сначала получите ссылку на файл, а затем вызовите метод download_to_stream для передачи содержимого файла в объект потока, который затем можно сохранить в локальном файле.To download files, first retrieve a file reference and then call the download_to_stream method to transfer the file contents to a stream object, which you can then persist to a local file. Кроме того, можно использовать метод download_to_file, чтобы скачать содержимое файла в локальный файл.Alternatively, you can use the download_to_file method to download the contents of a file to a local file. Вы можете также использовать метод download_text, чтобы скачать содержимое файла в виде текстовой строки.You can use the download_text method to download the contents of a file as a text string.

В следующем примере используются методы download_to_stream и download_text для демонстрации скачивания файлов, созданных в предыдущих разделах.The following example uses the download_to_stream and download_text methods to demonstrate downloading the files, which were created in previous sections.

// Download as text
azure::storage::cloud_file text_file =
  root_dir.get_file_reference(_XPLATSTR("my-sample-file-2"));
utility::string_t text = text_file.download_text();
ucout << "File Text: " << text << std::endl;

// Download as a stream.
azure::storage::cloud_file stream_file =
  root_dir.get_file_reference(_XPLATSTR("my-sample-file-3"));

concurrency::streams::container_buffer<std::vector<uint8_t>> buffer;
concurrency::streams::ostream output_stream(buffer);
stream_file.download_to_stream(output_stream);
std::ofstream outfile("DownloadFile.txt", std::ofstream::binary);
std::vector<unsigned char>& data = buffer.collection();
outfile.write((char *)&data[0], buffer.size());
outfile.close();

Удаление файлаDelete a file

Другая распространенная операция в службе файлов Azure — это удаление файлов.Another common Azure Files operation is file deletion. Следующий код удаляет файл с именем my-sample-file-3, который хранится в корневом каталоге.The following code deletes a file named my-sample-file-3 stored under the root directory.

// Get a reference to the root directory for the share.
azure::storage::cloud_file_share share =
  file_client.get_share_reference(_XPLATSTR("my-sample-share"));

azure::storage::cloud_file_directory root_dir =
  share.get_root_directory_reference();

azure::storage::cloud_file file =
  root_dir.get_file_reference(_XPLATSTR("my-sample-file-3"));

file.delete_file_if_exists();

Установка квоты (максимального размера) для общей папки Azure.Set the quota (maximum size) for an Azure file share

Для файлового ресурса можно установить квоту (или максимальный размер) в гигабайтах.You can set the quota (or maximum size) for a file share, in gigabytes. Можно также проверить, какой объем данных хранится в настоящее время в общей папке.You can also check to see how much data is currently stored on the share.

Задав квоту для файлового ресурса, можно ограничить общий размер файлов, хранящихся в общей папке.By setting the quota for a share, you can limit the total size of the files stored on the share. Если общий размер файлов в файловом ресурсе превышает установленную квоту, клиенты не смогут увеличить размер существующих файлов или создать новые файлы, только если они не являются пустыми.If the total size of files on the share exceeds the quota set on the share, then clients will be unable to increase the size of existing files or create new files, unless those files are empty.

В приведенном ниже примере показано, как проверить текущее использование данных в файловом ресурсе, а также задать для него квоту.The example below shows how to check the current usage for a share and how to set the quota for the share.

// Parse the connection string for the storage account.
azure::storage::cloud_storage_account storage_account =
  azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the file client.
azure::storage::cloud_file_client file_client =
  storage_account.create_cloud_file_client();

// Get a reference to the share.
azure::storage::cloud_file_share share =
  file_client.get_share_reference(_XPLATSTR("my-sample-share"));
if (share.exists())
{
    std::cout << "Current share usage: " << share.download_share_usage() << "/" << share.properties().quota();

    //This line sets the quota to 2560GB
    share.resize(2560);

    std::cout << "Quota increased: " << share.download_share_usage() << "/" << share.properties().quota();

}

Создание подписи общего доступа для файла или файлового ресурсаGenerate a shared access signature for a file or file share

Для файлового ресурса или отдельного файла можно создать подписанный URL-адрес (SAS).You can generate a shared access signature (SAS) for a file share or for an individual file. Также можно создать политики общего доступа на файловом ресурсе, чтобы управлять подписями общего доступа.You can also create a shared access policy on a file share to manage shared access signatures. Создание политики общего доступа рекомендуется, так как она позволяет отменить SAS, если она скомпрометирована.Creating a shared access policy is recommended, as it provides a means of revoking the SAS if it should be compromised.

В приведенном ниже примере создаются политики общего доступа в общей папке, а затем используются для обеспечения ограничения SAS для файла в общей папке.The following example creates a shared access policy on a share, and then uses that policy to provide the constraints for a SAS on a file in the share.

// Parse the connection string for the storage account.
azure::storage::cloud_storage_account storage_account =
  azure::storage::cloud_storage_account::parse(storage_connection_string);

// Create the file client and get a reference to the share
azure::storage::cloud_file_client file_client =
  storage_account.create_cloud_file_client();

azure::storage::cloud_file_share share =
  file_client.get_share_reference(_XPLATSTR("my-sample-share"));

if (share.exists())
{
    // Create and assign a policy
    utility::string_t policy_name = _XPLATSTR("sampleSharePolicy");

    azure::storage::file_shared_access_policy sharedPolicy =
      azure::storage::file_shared_access_policy();

    //set permissions to expire in 90 minutes
    sharedPolicy.set_expiry(utility::datetime::utc_now() +
       utility::datetime::from_minutes(90));

    //give read and write permissions
    sharedPolicy.set_permissions(azure::storage::file_shared_access_policy::permissions::write | azure::storage::file_shared_access_policy::permissions::read);

    //set permissions for the share
    azure::storage::file_share_permissions permissions;

    //retrieve the current list of shared access policies
    azure::storage::shared_access_policies<azure::storage::file_shared_access_policy> policies;

    //add the new shared policy
    policies.insert(std::make_pair(policy_name, sharedPolicy));

    //save the updated policy list
    permissions.set_policies(policies);
    share.upload_permissions(permissions);

    //Retrieve the root directory and file references
    azure::storage::cloud_file_directory root_dir =
        share.get_root_directory_reference();
    azure::storage::cloud_file file =
      root_dir.get_file_reference(_XPLATSTR("my-sample-file-1"));

    // Generate a SAS for a file in the share
    //  and associate this access policy with it.
    utility::string_t sas_token = file.get_shared_access_signature(sharedPolicy);

    // Create a new CloudFile object from the SAS, and write some text to the file.
    azure::storage::cloud_file file_with_sas(azure::storage::storage_credentials(sas_token).transform_uri(file.uri().primary_uri()));
    utility::string_t text = _XPLATSTR("My sample content");
    file_with_sas.upload_text(text);

    //Download and print URL with SAS.
    utility::string_t downloaded_text = file_with_sas.download_text();
    ucout << downloaded_text << std::endl;
    ucout << azure::storage::storage_credentials(sas_token).transform_uri(file.uri().primary_uri()).to_string() << std::endl;

}

Дальнейшие действияNext steps

Для получения дополнительных сведений о службе хранилища Azure изучите следующие ресурсы:To learn more about Azure Storage, explore these resources: