Клиентская библиотека BLOB-объектов службы хранилища Azure для JavaScript версии 12.17.0

Статья
11/10/2023

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

Этот проект предоставляет клиентскую библиотеку на Языке JavaScript, которая упрощает использование служба хранилища Microsoft Azure службе BLOB-объектов.

Используйте клиентские библиотеки в этом пакете, чтобы:

Получение и настройка свойств службы BLOB-объектов
Создание, перечисление и удаление контейнеров
Создание, чтение, перечисление, обновление и удаление блочных BLOB-объектов
Создание, чтение, перечисление, обновление и удаление страничных BLOB-объектов
Создание, чтение, перечисление, обновление и удаление добавочных BLOB-объектов

Ссылки на ключи

Начало работы

Поддерживаемые в настоящее время среды

LTS версии Node.js
Последние версии Safari, Chrome, Edge и Firefox.

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

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

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

Предпочтительным способом установки клиентской библиотеки BLOB-объектов службы хранилища Azure для JavaScript является использование диспетчера пакетов npm. В окне терминала введите следующее:

npm install @azure/storage-blob

Аутентификация клиента

Служба хранилища Azure поддерживает несколько способов проверки подлинности. Чтобы взаимодействовать со службой Хранилище BLOB-объектов Azure, необходимо создать экземпляр клиента хранилища, BlobServiceClientнапример , ContainerClientили BlobClient . Дополнительные сведения о проверке подлинности см. в BlobServiceClientпримерах создания .

Azure Active Directory
Общий ключ
Подписанные URL-адреса

Azure Active Directory

Служба Хранилище BLOB-объектов Azure поддерживает использование Azure Active Directory для проверки подлинности запросов к своим API. Пакет @azure/identity предоставляет различные типы учетных данных, которые приложение может использовать для этого. Дополнительные сведения и примеры см. в разделе README @azure/identity .

Совместимость

Эта библиотека совместима с Node.js и браузерами и проверена на соответствие версиям LTS Node.js (>=8.16.0) и последним версиям Chrome, Firefox и Edge.

Веб-рабочие роли

Эта библиотека требует, чтобы некоторые объекты DOM были глобально доступны при использовании в браузере, что веб-рабочие роли не делают доступными по умолчанию. Вам потребуется заполнить их, чтобы эта библиотека работала в веб-рабочих нагрузках.

Дополнительные сведения см. в нашей документации по использованию пакета Azure SDK для JS в веб-рабочих роях.

Эта библиотека зависит от следующих API-интерфейсов DOM, которым требуется загрузка внешних полизаполнения при использовании в веб-рабочих нагрузках:

Различия между Node.js и браузерами

Существуют различия между средой выполнения Node.js и браузерами. При начале работы с этой библиотекой обратите внимание на API-интерфейсы или классы, помеченные как "ДОСТУПНО ТОЛЬКО В NODE.JS RUNTIME" или "ТОЛЬКО ДОСТУПНО В БРАУЗЕРАХ".

Если большой двоичный объект содержит сжатые данные в gzip формате или deflate и его кодировка содержимого задана соответствующим образом, поведение скачивания в Node.js и браузерах отличается. В Node.js клиенты хранилища скачивают большой двоичный объект в сжатом формате, а в браузерах данные будут скачивание в формате распаки.

Функции, интерфейсы, классы или функции, доступные только в Node.js

Авторизация общего ключа на основе имени учетной записи и ключа учетной записи
- StorageSharedKeyCredential
Создание подписанного URL-адреса (SAS)
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Параллельная отправка и скачивание. Обратите внимание, что BlockBlobClient.uploadData() доступен как в Node.js, так и в браузерах.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Функции, интерфейсы, классы или функции, доступные только в браузерах

Параллельная отправка и скачивание
- BlockBlobClient.uploadBrowserData()

Пакет JavaScript

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

CORS

Для разработки для браузеров необходимо настроить правила общего доступа к ресурсам независимо от источника (CORS) для учетной записи хранения. Перейдите к портал Azure и Обозреватель службы хранилища Azure, найдите свою учетную запись хранения, создайте новые правила CORS для служб BLOB-объектов, очередей, файлов и таблиц.

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

Допустимые источники: *
Допустимые глаголы: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Разрешенные заголовки: *
Доступные заголовки: *
Максимальный возраст (в секундах): 86400

Основные понятия

Хранилище BLOB-объектов предназначено для следующих задач:

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

В хранилище BLOB-объектов предлагается три типа ресурсов:

Учетная запись хранения, используемая черезBlobServiceClient
Контейнер в учетной записи хранения, используемой с помощьюContainerClient
Большой двоичный объект в контейнере, используемый с помощьюBlobClient

Примеры

Импорт пакета
Создание клиента службы BLOB-объектов
Создает контейнер.
Вывод списка контейнеров
Создание большого двоичного объекта путем отправки данных
Вывод списка BLOB-объектов в контейнере
Скачивание большого двоичного объекта и преобразование его в строку (Node.js)
Скачивание большого двоичного объекта и его преобразование в строку (браузеры)

Импорт пакета

Чтобы использовать клиенты, импортируйте пакет в файл:

const AzureStorageBlob = require("@azure/storage-blob");

Кроме того, можно выборочно импортировать только необходимые типы:

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

Создание клиента службы BLOB-объектов

Для BlobServiceClient требуется URL-адрес службы BLOB-объектов и учетные данные для доступа. Он также при необходимости принимает некоторые параметры в параметре options .

с `DefaultAzureCredential` из `@azure/identity` пакета

Рекомендуемый способ создания экземпляра BlobServiceClient

Настройка: справочник. Авторизация доступа к BLOB-объектам и очередям с помощью Azure Active Directory из клиентского приложения — /azure/storage/common/storage-auth-aad-app

Регистрация нового приложения AAD и предоставление разрешений на доступ к службе хранилища Azure от имени вошедшего пользователя
- Регистрация нового приложения в Azure Active Directory (на портале azure) — /azure/active-directory/develop/quickstart-register-app
- API permissions В разделе выберите Add a permission и выберите Microsoft APIs.
- Установите Azure Storage и установите флажок рядом с и нажмите кнопку user_impersonationAdd permissions. Это позволит приложению получить доступ к службе хранилища Azure от имени вошедшего пользователя.
Предоставление доступа к данным BLOB-объектов Azure с помощью RBAC на портале Azure
- Роли RBAC для больших двоичных объектов и очередей — /azure/storage/common/storage-auth-aad-rbac-portal.
- На портале Azure перейдите к учетной записи хранения и назначьте роль участника данных BLOB-объектов хранилища зарегистрированным приложениям AAD с Access control (IAM) вкладки (на панели навигации слева учетной записи хранения на портале azure).
Настройка среды для примера
- На странице обзора приложения AAD запишите CLIENT ID и TENANT ID. На вкладке "Сертификаты & Секреты" создайте секрет и запишите его вниз.
- Убедитесь, что AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET в качестве переменных среды для успешного выполнения примера(Может использовать process.env).

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

Полный пример использования этого метода см. в примере проверки подлинности Azure AD.

[Примечание. Описанные выше действия предназначены только для Node.js]

использование строка подключения

Кроме того, можно создать BlobServiceClient экземпляр с помощью fromConnectionString() статического метода с полным строка подключения в качестве аргумента . (Строка подключения можно получить на портале Azure.) [ДОСТУПНО ТОЛЬКО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS]

const { BlobServiceClient } = require("@azure/storage-blob");

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

С `StorageSharedKeyCredential`

Кроме того, можно создать BlobServiceClient экземпляр с StorageSharedKeyCredential , передав имя учетной записи и ключ учетной записи в качестве аргументов. (Имя учетной записи и ключ учетной записи можно получить на портале Azure.) [ДОСТУПНО ТОЛЬКО В СРЕДЕ ВЫПОЛНЕНИЯ NODE.JS]

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential
);

с маркером SAS

Кроме того, можно создать BlobServiceClient экземпляр с подписанными URL-адресами (SAS). Вы можете получить маркер SAS на портале Azure или создать его с помощью generateAccountSASQueryParameters().

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);

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

Используйте BlobServiceClient.getContainerClient() для получения экземпляра клиента контейнера, а затем создайте новый ресурс контейнера.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  // Create a container
  const containerName = `newcontainer${new Date().getTime()}`;
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse = await containerClient.create();
  console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);
}

main();

Вывод списка контейнеров

Используйте BlobServiceClient.listContainers() функцию для итерации контейнеров с новым for-await-of синтаксисом:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let containers = blobServiceClient.listContainers();
  for await (const container of containers) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

main();

Кроме того, без использования for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  let iter = blobServiceClient.listContainers();
  let containerItem = await iter.next();
  while (!containerItem.done) {
    console.log(`Container ${i++}: ${containerItem.value.name}`);
    containerItem = await iter.next();
  }
}

main();

Кроме того, для перечисления также поддерживается разбиение на страницы через byPage():

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

async function main() {
  let i = 1;
  for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
    if (response.containerItems) {
      for (const container of response.containerItems) {
        console.log(`Container ${i++}: ${container.name}`);
      }
    }
  }
}

main();

Полный пример итерации контейнеров см. в разделе samples/v12/typescript/src/listContainers.ts.

Создание большого двоичного объекта путем отправки данных

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  const content = "Hello world!";
  const blobName = "newblob" + new Date().getTime();
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);
  const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
  console.log(`Upload block blob ${blobName} successfully`, uploadBlobResponse.requestId);
}

main();

Вывод списка BLOB-объектов в контейнере

Аналогично перечислению контейнеров.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  let i = 1;
  let blobs = containerClient.listBlobsFlat();
  for await (const blob of blobs) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

main();

Полный пример итерации больших двоичных объектов см. в разделе samples/v12/typescript/src/listBlobsFlat.ts.

Скачивание большого двоичного объекта и преобразование его в строку (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential
);

const containerName = "<container name>";
const blobName = "<blob name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = (
    await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
  ).toString();
  console.log("Downloaded blob content:", downloaded);

  // [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
  async function streamToBuffer(readableStream) {
    return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on("data", (data) => {
        chunks.push(data instanceof Buffer ? data : Buffer.from(data));
      });
      readableStream.on("end", () => {
        resolve(Buffer.concat(chunks));
      });
      readableStream.on("error", reject);
    });
  }
}

main();

Скачайте большой двоичный объект и преобразуйте его в строку (браузеры).

Дополнительные сведения об использовании этой библиотеки в браузере см. в разделе Пакет JavaScript .

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net${sas}`);

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
  console.log("Downloaded blob content", downloaded);

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob) {
    const fileReader = new FileReader();
    return new Promise((resolve, reject) => {
      fileReader.onloadend = (ev) => {
        resolve(ev.target.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

Полный пример простых сценариев приведен в samples/v12/typescript/src/sharedKeyAuth.ts.

Устранение неполадок

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

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

Дополнительные примеры кода:

Участие

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

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

Просмотры

Клиентская библиотека BLOB-объектов службы хранилища Azure для JavaScript версии 12.17.0

Начало работы

Поддерживаемые в настоящее время среды

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

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

Аутентификация клиента

Azure Active Directory

Совместимость

Веб-рабочие роли

Различия между Node.js и браузерами

Функции, интерфейсы, классы или функции, доступные только в Node.js

Функции, интерфейсы, классы или функции, доступные только в браузерах

Пакет JavaScript

CORS

Основные понятия

Примеры

Импорт пакета

Создание клиента службы BLOB-объектов

с `DefaultAzureCredential` из `@azure/identity` пакета

использование строка подключения

С `StorageSharedKeyCredential`

с маркером SAS

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

Вывод списка контейнеров

Создание большого двоичного объекта путем отправки данных

Вывод списка BLOB-объектов в контейнере

Скачивание большого двоичного объекта и преобразование его в строку (Node.js)

Скачайте большой двоичный объект и преобразуйте его в строку (браузеры).

Устранение неполадок

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

Участие

Обратная связь

Дополнительные ресурсы

Клиентская библиотека BLOB-объектов службы хранилища Azure для JavaScript версии 12.17.0

Начало работы

Поддерживаемые в настоящее время среды

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

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

Аутентификация клиента

Azure Active Directory

Совместимость

Веб-рабочие роли

Различия между Node.js и браузерами

Функции, интерфейсы, классы или функции, доступные только в Node.js

Функции, интерфейсы, классы или функции, доступные только в браузерах

Пакет JavaScript

CORS

Основные понятия

Примеры

Импорт пакета

Создание клиента службы BLOB-объектов

с DefaultAzureCredential из @azure/identity пакета

использование строка подключения

С StorageSharedKeyCredential

с маркером SAS

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

Вывод списка контейнеров

Создание большого двоичного объекта путем отправки данных

Вывод списка BLOB-объектов в контейнере

Скачивание большого двоичного объекта и преобразование его в строку (Node.js)

Скачайте большой двоичный объект и преобразуйте его в строку (браузеры).

Устранение неполадок

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

Участие

Обратная связь

Дополнительные ресурсы

с `DefaultAzureCredential` из `@azure/identity` пакета

С `StorageSharedKeyCredential`