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

Статья
11/20/2024

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

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

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

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

Ключевые ссылки

исходный код.
Пакет (npm)
Справочная документация по API
документации по продукту
Примеры
REST API хранилища Azure

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

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

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

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

Необходимые условия

подписки Azure
учетной записи хранения

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

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

npm install @azure/storage-blob

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

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

Azure Active Directory
общий ключ
подписей общего доступа

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 были глобально доступны при использовании в браузере, которые веб-работники по умолчанию не делают доступными. Эти библиотеки необходимо заполнить, чтобы эта библиотека работала в веб-рабочих нагрузках.

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

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

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

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

Если большой двоичный объект содержит сжатые данные в 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 для больших двоичных объектов, очередей, файлов и таблиц.

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

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

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

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

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

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

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

Примеры

Импорт пакета
Создание клиента службы 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_impersonation и щелкните Add 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 см. в примера проверки подлинности 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;
  const 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;
  const 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();

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

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

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;
  const 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-объектов (JavaScript)
примеры хранилища BLOB-объектов (TypeScript)
тестовые случаи хранилища BLOB-объектов

Способствует

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

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

впечатлений

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

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

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

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

Необходимые условия

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

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

Azure Active Directory

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

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

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

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

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

Пакет JavaScript

CORS

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

Примеры

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

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

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

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

с `StorageSharedKeyCredential`

с маркером SAS

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

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

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

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

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

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

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

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

Способствует

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

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

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

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

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

Необходимые условия

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

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

Azure Active Directory

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

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

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

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

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

Пакет JavaScript

CORS

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

Примеры

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

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

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

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

с StorageSharedKeyCredential

с маркером SAS

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

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

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

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

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

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

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

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

Способствует

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

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

с `StorageSharedKeyCredential`