Краткое руководство. Клиентская библиотека хранилища BLOB-объектов Azure для Node.js с TypeScript

Начните работу с клиентской библиотекой Хранилище BLOB-объектов Azure для Node.js с TypeScript для управления BLOB-объектами и контейнерами.

В этой статье описано, как установить пакет и попробовать пример кода для основных задач.

Справочник по API | Исходный код библиотеки | Пакет (npm) | Примеры

Предварительные требования

Настройка

В этом разделе пошагово описывается подготовка проекта для работы с клиентской библиотекой Хранилища BLOB-объектов Azure для Node.js.

Создание проекта Node.js

Создайте приложение TypeScript с именем BLOB-quickstart.

  1. В окне консоли (например, cmd, PowerShell или Bash) создайте новый каталог для проекта:

    mkdir blob-quickstart

  2. Перейдите в только что созданный каталог blob-quickstart :

    cd blob-quickstart

  3. Создайте файл package.json:

    npm init -y

  4. Откройте проект в Visual Studio Code:

    code .

  5. Измените файл package.json , чтобы добавить следующие свойства для поддержки ESM с typeScript:

    "type": "module",

Установка пакетов

В каталоге проекта установите следующие пакеты с помощью npm install команды.

  1. Установите пакет npm для службы хранилища Azure:

    npm install @azure/storage-blob

  2. Установите другие зависимости, используемые в этом кратком руководстве:

    npm install uuid dotenv @types/node @types/uuid

  3. tsconfig.json Создайте файл в каталоге проекта со следующим содержимым.

    {
    "compilerOptions": {
      "target": "es2022",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
      "module": "ESNext",                                /* Specify what module code is generated. */
      "moduleResolution": "node",                     /* Specify how TypeScript looks up a file from a given module specifier. */
      "outDir": "dist",                                   /* Specify an output folder for all emitted files. */
      "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
      "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
      "strict": true,                                      /* Enable all strict type-checking options. */
      "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
    }
  }

Объектная модель

Хранилище BLOB-объектов Azure оптимизировано для хранения больших объемов неструктурированных данных. Неструктурированные данные — это данные, которые не соответствуют определенной модели данных или определению, например текстовых или двоичных данных. Хранилище BLOB-объектов поддерживает три типа ресурсов:

  • учетная запись хранения;
  • Контейнер в учетной записи хранения
  • BLOB-объект в контейнере

На следующей схеме показана связь между этими ресурсами.

Схема архитектуры хранилища BLOB-объектов.

Используйте следующие классы JavaScript для взаимодействия с этими ресурсами.

  • BlobServiceClient: класс BlobServiceClient позволяет управлять ресурсами службы хранилища Azure и контейнерами BLOB-объектов.
  • ContainerClient: Класс ContainerClient позволяет управлять контейнерами служба хранилища Azure и их BLOB-объектами.
  • BlobClient: класс BlobClient позволяет управлять BLOB-объектами службы хранилища Azure.

Примеры кода

В этих примерах фрагментов кода показано, как выполнять следующие задачи с помощью клиентской библиотеки Хранилище BLOB-объектов Azure для JavaScript:

Пример кода также доступен на сайте GitHub.

Пройдите аутентификацию в Azure и авторизуйте доступ к данным BLOB-объектов

Запросы приложений к Хранилищу BLOB-объектов Azure должны быть авторизованы. Использование класса DefaultAzureCredential, предоставляемого клиентской библиотекой Azure Identity, — это рекомендуемый способ создания в коде подключений к службам Azure без пароля, включая Хранилище BLOB-объектов.

Вы также можете авторизовать запросы к Хранилищу BLOB-объектов Azure с помощью ключа доступа к учетной записи. Однако этот подход следует использовать с осторожностью. Разработчики должны тщательно следить за тем, чтобы не раскрыть ключи доступа в незащищенном расположении. Любой пользователь, имеющий ключ доступа, может авторизовать запросы к учетной записи хранения и эффективно иметь доступ ко всем данным. DefaultAzureCredential предлагает улучшенные преимущества управления и безопасности по сравнению с ключом учетной записи, чтобы разрешить проверку подлинности без пароля. Оба варианта показаны в следующем примере.

DefaultAzureCredential поддерживает несколько способов проверки подлинности и определяет, какой из них следует использовать в среде выполнения. Такой подход позволяет приложению использовать различные способы проверки подлинности в разных средах (локальной и рабочей) без реализации кода для конкретной среды.

Порядок и расположения, в которых DefaultAzureCredential выполняет поиск учетных данных, можно найти в обзоре библиотеки удостоверений Azure.

Например, при локальной разработке приложение может проходить аутентификацию с помощью учетных данных для входа в Azure CLI. Затем приложение может использовать управляемое удостоверение после его развертывания в Azure. Для такого перехода не требуется изменять код.

Назначение ролей учетной записи пользователя Microsoft Entra

Если вы выполняете разработку локально, убедитесь, что учетная запись пользователя, через которую осуществляется доступ к данным BLOB-объектов, имеет правильные разрешения. Вам потребуется участник данных BLOB-объектов хранилища для чтения и записи данных BLOB-объектов. Чтобы назначить себе эту роль, вам должна быть назначена роль User Access Administrator или другая роль, включающая действие Microsoft.Authorization/roleAssignments/write. Роли Azure RBAC можно назначить пользователю с помощью портала Azure, Azure CLI или Azure PowerShell. Дополнительные сведения о роли участника данных BLOB-объектов хранилища см. в разделе "Участник данных BLOB-объектов хранилища". Дополнительные сведения о доступных областях назначения ролей см. в статье "Общие сведения о области для Azure RBAC".

В этом сценарии вы назначите разрешения своей учетной записи, область действия которых ограничена учетной записью хранения, чтобы следовать принципу наименьших привилегий. В рамках этой практики пользователям предоставляются только минимальные необходимые разрешения, что позволяет создавать более защищенные рабочие среды.

В следующем примере вашей учетной записи пользователя будет назначена роль Storage Blob Data Contributor, которая предоставляет права как на чтение, так и на запись данных BLOB-объектов в вашей учетной записи хранения.

Внимание

В большинстве случаев для распространения назначения ролей в Azure потребуется минута или две, но в редких случаях может потребоваться до восьми минут. Если при первом запуске кода возникают ошибки аутентификации, подождите несколько минут и повторите попытку.

  1. На портале Azure найдите свою учетную запись хранения, воспользовавшись основной панелью поиска или областью навигации слева.

  2. На странице обзора учетной записи хранения выберите Контроль доступа (IAM) в меню слева.

  3. На странице Контроль доступа (IAM) откройте вкладку Назначения ролей.

  4. Выберите + Добавить в верхнем меню, а затем выберите Добавить назначение роли в появившемся раскрывающемся меню.

    Снимок экрана, на котором продемонстрировано назначение роли.

  5. Используйте поле поиска, чтобы отфильтровать результаты для отображения нужной роли. В этом примере найдите Storage Blob Data Contributor, выберите соответствующий результат, а затем выберите Далее.

  6. В разделе Назначить доступ к, выберите Пользователь, группа или субъект-служба, а затем — + Выбрать участников.

  7. В диалоговом окне найдите имя пользователя Microsoft Entra (обычно это ваш адрес электронной почты user@domain), а затем в нижней части диалогового окна выберите Выбрать.

  8. Нажмите кнопку Проверить и назначить, чтобы перейти на последнюю страницу, а затем еще раз Проверить и назначить, чтобы завершить процесс.

Войдите и подключите код приложения к Azure с помощью DefaultAzureCredential

Чтобы авторизовать доступ к данным в учетной записи хранения, выполните следующие действия:

  1. Убедитесь, что вы выполнили вход с той же учетной записью Microsoft Entra, которой назначили роль для своей учетной записи хранения. Вы можете пройти проверку подлинности с помощью Azure CLI, Visual Studio Code или Azure PowerShell.

    Войдите в Azure с помощью Azure CLI, выполнив следующую команду:

    az login

  2. Чтобы использовать DefaultAzureCredential, убедитесь, что пакет @azure\identityустановлен, а класс импортирован:

    import { DefaultAzureCredential } from '@azure/identity';

  3. Добавьте этот код в try блок. Когда код выполняется на локальной рабочей станции, DefaultAzureCredential использует учетные данные разработчика из приоритетного инструмента, в который выполнен вход, для аутентификации в Azure. Примерами этих средств являются Azure CLI или Visual Studio Code.

    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
if (!accountName) throw Error('Azure Storage accountName not found');

// Add `Storage Blob Data Contributor` role assignment to the identity
const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

  4. Обязательно обновите имя учетной записи хранения в AZURE_STORAGE_ACCOUNT_NAME.env файле или переменных среды. Имя учетной записи хранения можно найти на странице обзора портала Azure.

    Снимок экрана: как найти имя учетной записи хранения.

    Примечание.

    При развертывании в Azure этот же код можно использовать для авторизации запросов к службе хранилища Azure из приложения, работающего в Azure. Однако вам необходимо включить управляемое удостоверение в приложении в Azure. Затем настройте учетную запись хранилища так, чтобы это управляемое удостоверение могло подключаться к ней. Подробные инструкции по настройке этого подключения между службами Azure см. в учебнике по проверке подлинности в приложениях, размещенных в Azure.

Создание контейнера

Создайте новый контейнер в учетной записи хранения. В следующем примере кода принимается объект BlobServiceClient и вызывается метод getContainerClient, чтобы получить ссылку на контейнер. Затем код вызывает метод создания , чтобы фактически создать контейнер в учетной записи хранения.

Добавьте следующий код в конец блока try.

  const containerName = 'quickstart' + uuidv4();

  console.log('\nCreating container...');
  console.log('\t', containerName);

  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse: ContainerCreateResponse = await containerClient.create();
  console.log(
    `Container was created successfully.\n\trequestId:${createContainerResponse.requestId}\n\tURL: ${containerClient.url}`
  );

Дополнительные сведения о создании контейнера и изучении дополнительных примеров кода см. в статье "Создание контейнера BLOB-объектов с помощью JavaScript".

Внимание

Имена контейнеров должны состоять из знаков нижнего регистра. Дополнительные сведения об именовании контейнеров и больших двоичных объектов см. в статье Naming and Referencing Containers, Blobs, and Metadata (Именование контейнеров, больших двоичных объектов и метаданных и ссылка на них).

Загрузка BLOB-объектов в контейнер

Загрузите BLOB-объект в контейнер. Следующий код получает ссылку на объект BlockBlobClient путем вызова метода getBlockBlobClient для объекта ContainerClient из раздела Создание контейнера.

Код загружает данные текстовой строки в BLOB-объект с помощью метода upload.

Добавьте следующий код в конец блока try.

  const blobName = 'quickstart' + uuidv4(); + '.txt';
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  console.log(
    `\nUploading to Azure storage as blob\n\tname: ${blobName}:\n\tURL: ${blockBlobClient.url}`
  );

  const data = 'Hello, World!';
  const uploadBlobResponse: BlockBlobUploadResponse = await blockBlobClient.upload(data, data.length);
  console.log(
    `Blob was uploaded successfully. requestId: ${uploadBlobResponse.requestId}`
  );

Дополнительные сведения о отправке больших двоичных объектов и изучении дополнительных примеров кода см. в статье "Отправка большого двоичного объекта с помощью JavaScript".

Перечисление BLOB-объектов в контейнере

Создайте список BLOB-объектов в контейнере. Следующий код вызывает метод listBlobsFlat . В этом случае в контейнере находится только один BLOB-объект, поэтому операция получения списка возвращает только этот BLOB-объект.

Добавьте следующий код в конец блока try.

  console.log('\nListing blobs...');

  for await (const blob of containerClient.listBlobsFlat()) {
    const tempBlockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blob.name);

    console.log(
      `\n\tname: ${blob.name}\n\tURL: ${tempBlockBlobClient.url}\n`
    );
  }

Дополнительные сведения о перечислении больших двоичных объектов и дополнительные примеры кода см. в статье "Список БОЛЬШИХ двоичных объектов" с помощью JavaScript.

Скачать BLOB-объекты

Скачайте BLOB-объект и отобразите его содержимое. Следующий код вызывает метод download, чтобы скачать объект BLOB.

Добавьте следующий код в конец блока try.

  const offset = 0;         // start at beginning
  const length = undefined; // read all

  const downloadBlockBlobResponse: BlobDownloadResponseParsed = await blockBlobClient.download(offset, length);
  console.log('\nDownloaded blob content...');
  console.log(
    '\t',
    await streamToText(downloadBlockBlobResponse.readableStreamBody as NodeJS.ReadableStream)
  );

Следующий код преобразует поток обратно в строку для отображения содержимого.

Добавьте этот код после функции main:

// Convert stream to text
async function streamToText(readable: NodeJS.ReadableStream): Promise<string> {
  readable.setEncoding('utf8');
  let data = '';
  for await (const chunk of readable) {
    data += chunk;
  }
  return data;
}

Дополнительные сведения о скачивании больших двоичных объектов и дополнительные примеры кода см. в статье "Скачать большой двоичный объект с помощью JavaScript".

Удаление контейнера

Удалите контейнер и все BLOB-объекты внутри него. Следующий код очищает ресурсы, созданные приложением, путем удаления всего контейнера с помощью метода удаления .

Добавьте следующий код в конец блока try.

  console.log('\nDeleting container...');

  const deleteContainerResponse: ContainerDeleteResponse = await containerClient.delete();
  console.log(
    'Container was deleted successfully. requestId: ',
    deleteContainerResponse.requestId
  );

Дополнительные сведения об удалении контейнера и изучении дополнительных примеров кода см. в статье "Удаление и восстановление контейнера BLOB-объектов с помощью JavaScript".

Выполнение кода

  1. В терминале Visual Studio Code создайте приложение.

    tsc

  2. Запустите приложение.

    node dist/index.js

  3. Результат работы приложения будет примерно таким, как в следующем примере:

    Azure Blob storage - JavaScript quickstart sample

Creating container...
    quickstart4a0780c0-fb72-11e9-b7b9-b387d3c488da

Uploading to Azure Storage as blob:
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Listing blobs...
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Downloaded blob content...
    Hello, World!

Deleting container...
Done

Пошагово выполните код в отладчике и просматривайте результаты на портале Azure. Проверьте, создан ли контейнер. Вы можете открыть BLOB-объект в контейнере и просмотреть его содержимое.

Очистка ресурсов

  1. По завершении работы с этим кратким руководством удалите каталог blob-quickstart.
  2. Если вы не планируете дальше использовать ресурс службы хранилища Azure, удалите его с помощью Azure CLI.

Следующий шаг

Служба хранилища Azure: примеры и руководства для разработчиков по JavaScript и TypeScript

  • Last updated on