Прочитать на английском

Поделиться через

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

  • Статья
Выбор способа взаимодействия с кратким руководством

Примечание

В разделе "Сборка с нуля " пошаговые инструкции по созданию проекта, установке пакетов, написанию кода и запуску базового консольного приложения. Этот подход рекомендуется, если вы хотите понять все сведения, связанные с созданием приложения, которое подключается к Хранилище BLOB-объектов Azure. Если вы предпочитаете автоматизировать задачи развертывания и начинать работу с завершенным проектом, выберите "Начать с шаблона".

Примечание

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

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

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

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

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

Необходимые компоненты

Установка

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

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

Создайте приложение JavaScript с именем 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 .

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

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

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

    npm install @azure/storage-blob

  2. Установите пакет npm удостоверений Azure для подключения без пароля:

    npm install @azure/identity

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

    npm install uuid dotenv

Настройка платформы приложения

Из каталога проекта:

  1. Создание файла с именем index.js

  2. Скопируйте следующий код в файл:

    const { BlobServiceClient } = require("@azure/storage-blob");
const { v1: uuidv1 } = require("uuid");
require("dotenv").config();

async function main() {
  try {
    console.log("Azure Blob storage v12 - JavaScript quickstart sample");

    // Quick start code goes here



  } catch (err) {
    console.err(`Error: ${err.message}`);
  }
}

main()
  .then(() => console.log("Done"))
  .catch((ex) => console.log(ex.message));

С установленным интерфейсом командной строки разработчика Azure можно создать учетную запись хранения и запустить пример кода с помощью нескольких команд. Проект можно запустить в локальной среде разработки или в DevContainer.

Инициализация шаблона интерфейса командной строки разработчика Azure и развертывание ресурсов

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

  • Клонируйте ресурсы репозитория быстрого запуска из GitHub и инициализирует шаблон локально:

    azd init --template blob-storage-quickstart-nodejs

    Вам будет предложено получить следующие сведения:

    • Имя среды: это значение используется в качестве префикса для всех ресурсов Azure, созданных Azure Developer CLI. Имя должно быть уникальным для всех подписок Azure и должно составлять от 3 до 24 символов. Имя может содержать только цифры и строчные буквы.

  • Войдите в Azure.

    azd auth login

  • Подготовка и развертывание ресурсов в Azure:

    azd up

    Вам будет предложено получить следующие сведения:

    • Подписка: подписка Azure, в которую развертываются ваши ресурсы.
    • Расположение: регион Azure, в котором развернуты ресурсы.

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

Запуск примера кода

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

  1. Установка пакетов. Перейдите к локальному blob-quickstart каталогу. Установите пакеты для клиентских библиотек Хранилище BLOB-объектов Azure и удостоверений Azure, а также другие пакеты, используемые в кратком руководстве, с помощью следующей команды:
    npm install @azure/storage-blob @azure/identity uuid dotenv
  2. Обновите имя учетной записи хранения: в локальном blob-quickstart каталоге измените файл с именем index.js. <storage-account-name> Найдите заполнитель и замените его фактическим именем учетной записи хранения, созданной командойazd up. Сохраните изменения.
  3. Запустите проект: выполните следующую команду, чтобы запустить приложение: 
    node index.js
  4. Просмотрите выходные данные: это приложение создает контейнер и отправляет текстовую строку в виде большого двоичного объекта в контейнер. Затем в примере перечислены большие двоичные объекты в контейнере и скачивают большой двоичный объект и отображаются содержимое большого двоичного объекта. Затем приложение удаляет контейнер и все его большие двоичные объекты.

Дополнительные сведения о работе примера кода см . в примерах кода.

После завершения тестирования кода см . раздел "Очистка ресурсов ", чтобы удалить ресурсы, созданные командой azd up .

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

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

  • учетная запись хранения;
  • контейнер в учетной записи хранения;
  • большой двоичный объект в контейнере.

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

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

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

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

Примеры кода

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

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

Примечание

Шаблон ИНТЕРФЕЙСА командной строки разработчика Azure содержит файл с примером кода. В следующих примерах приведены подробные сведения для каждой части примера кода. Шаблон реализует рекомендуемый метод проверки подлинности без пароля, как описано в разделе "Проверка подлинности в Azure ". Метод строка подключения отображается как альтернатива, но не используется в шаблоне и не рекомендуется для рабочего кода.

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

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

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

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

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

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

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

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

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

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

Важно!

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

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

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

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

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

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

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

  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, а класс импортируется:

    const { DefaultAzureCredential } = require('@azure/identity');

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

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

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.

// Create a unique name for the container
const containerName = 'quickstart' + uuidv1();

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

// Get a reference to a container
const containerClient = blobServiceClient.getContainerClient(containerName);
// Create the container
const createContainerResponse = 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 (Именование контейнеров, больших двоичных объектов и метаданных и ссылка на них).

отправка больших двоичных объектов в контейнер;

Отправьте в этот контейнер большой двоичный объект. Следующий код получает ссылку на объект BlockBlobClient, вызвав метод getBlockBlobClient в КонтейнереClient из раздела "Создание контейнера".

Код передает данные текстовой строки в большой двоичный объект, вызывая метод upload.

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

// Create a unique name for the blob
const blobName = 'quickstart' + uuidv1() + '.txt';

// Get a block blob client
const blockBlobClient = containerClient.getBlockBlobClient(blobName);

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

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

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

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

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

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

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

// List the blob(s) in the container.
for await (const blob of containerClient.listBlobsFlat()) {
  // Get Blob Client from name, to get the URL
  const tempBlockBlobClient = containerClient.getBlockBlobClient(blob.name);

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

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

скачивание больших двоичных объектов;

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

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

// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blockBlobClient.download(0);
console.log('\nDownloaded blob content...');
console.log(
  '\t',
  await streamToText(downloadBlockBlobResponse.readableStreamBody)
);

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

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

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

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

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

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

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

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

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

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

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

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

node index.js

Вы должны увидеть выходные данные приложения, как показано ниже.

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. Проверьте, создан ли контейнер. Вы можете открыть большой двоичный объект в контейнере и просмотреть его содержимое.

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

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

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

azd down

Вам будет предложено подтвердить удаление ресурсов. Введите y для подтверждения.

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

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