Начало работы с Хранилищем BLOB-объектов Azure и JavaScript

• .NET
• Java
• JavaScript
• TypeScript
• Python

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

Примеры фрагментов кода доступны на GitHub в виде исполняемых файлов Node.js.

Примеры | исходного кода | библиотеки с справочником | по API (npm) | Дают отзыв

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

• Подписка Azure — создайте бесплатную учетную запись.
• Учетная запись хранения Azure — создайте такую учетную запись.
• LTS Node.js
• Для клиентских (браузерных) приложений требуются средства объединение.

Настройка проекта

1. Откройте командную строку и перейдите в папку проекта. Измените YOUR-DIRECTORY имя папки:

   cd YOUR-DIRECTORY
   

2. Если у вас в каталоге еще нет файла package.json, инициализируйте проект, чтобы создать файл:

   npm init -y
   

3. Установите клиентскую библиотеку Хранилища BLOB-объектов Azure для JavaScript:

   npm install @azure/storage-blob
   

4. Если вы хотите использовать бессерверные подключения с помощью идентификатора Microsoft Entra, установите клиентскую библиотеку удостоверений Azure для JavaScript:

   npm install @azure/identity
   

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

Идентификатор Microsoft Entra предоставляет наиболее безопасное подключение, управляя удостоверением подключения (управляемым удостоверением). Эта функция без пароля позволяет разрабатывать приложение, которое не требует каких-либо секретов (ключей или строка подключения), хранящихся в коде.

Настройка доступа к удостоверениям в облаке Azure

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

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

Среда	Метод
Среда разработчика	Visual Studio Code
Среда разработчика	Субъект-служба
Приложения, размещенные в Azure	Настройка размещенных в Azure приложений
Локально	Настройка локального приложения

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

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

После завершения установки каждое удостоверение должно иметь по крайней мере одну из соответствующих ролей:

• Роль доступа к данным, например:

  • читатель данных больших двоичных объектов хранилища.
  • участник данных BLOB-объектов хранилища;

• Роль ресурса, например:

  • Читатель
  • Участник

Сборка приложения

При создании приложения код будет в основном взаимодействовать с тремя типами ресурсов:

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

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

Каждый тип ресурса представлен одним или несколькими связанными клиентами JavaScript:

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

Создание объекта BlobServiceClient

Объект BlobServiceClient — это верхний объект в пакете SDK. Этот клиент позволяет управлять службой, контейнерами и BLOB-объектами.

Без пароля

После настройки ролей удостоверений учетной записи хранения Azure и локальной @azure/identity среды создайте файл JavaScript, включающий пакет. Создайте учетные данные, такие как DefaultAzureCredential, для реализации бессерверных подключений к BLOB-объектам служба хранилища. Используйте эти учетные данные для проверки подлинности с помощью объекта BlobServiceClient .

// connect-with-default-azure-credential.js
const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');
require('dotenv').config()

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()
);

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

Пакет dotenv используется для чтения имени учетной .env записи хранения из файла. Этот файл не должен быть проверка в управление версиями. Если вы используете локальный субъект-службу в рамках настройки DefaultAzureCredential, все сведения о безопасности для этих учетных данных также будут входить в .env файл.

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

Ключ учетной записи

Создайте служба хранилища SharedKeyCredential из имени учетной записи хранения и ключа учетной записи. Затем передайте служба хранилища SharedKeyCredential конструктору класса BlobServiceClient для создания клиента.

// connect-with-account-name-and-key.js
const { BlobServiceClient, StorageSharedKeyCredential } = require('@azure/storage-blob');
require('dotenv').config()

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

const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);

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

async function main() {

  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);

}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

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

Сведения о получении ключей учетной записи и рекомендации по правильному управлению и защите ключей см. в статье Управление ключами доступа к учетной записи хранения.

Маркер SAS

Создайте URI для ресурса с помощью конечной точки службы BLOB-объектов и маркера SAS. Затем создайте BlobServiceClient с помощью этого URI. Маркер SAS — это ряд пар "имя-значение" в строках запросов в формате, например:

https://YOUR-RESOURCE-NAME.blob.core.windows.net?YOUR-SAS-TOKEN

В зависимости от того, какое средство, используемое для создания маркера SAS, ? может быть уже добавлено в маркер SAS.

// connect-with-sas-token.js
const { BlobServiceClient } = require('@azure/storage-blob');
require('dotenv').config()

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

const blobServiceUri = `https://${accountName}.blob.core.windows.net`;

// https://YOUR-RESOURCE-NAME.blob.core.windows.net?YOUR-SAS-TOKEN
const blobServiceClient = new BlobServiceClient(
  `${blobServiceUri}?${sasToken}`,
  null
);

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

Пакет dotenv используется для чтения имени учетной .env записи хранения и маркера SAS из файла. Этот файл не должен быть проверка в управление версиями.

Сведения о создании маркеров SAS и управлении ими см. в следующих статьях:

• Предоставление ограниченного доступа к ресурсам службы хранилища Azure с помощью подписанных URL-адресов (SAS)

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

Создание объекта ContainerClient

Объект ContainerClient можно создать из blobServiceClient или напрямую.

Создание объекта ContainerClient из BlobServiceClient

Создайте объект ContainerClient из BLOBServiceClient.

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

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

// Create BlobServiceClient
const blobServiceClient = new BlobServiceClient(
  `${baseUrl}`,
  sharedKeyCredential
);

async function main() {
  try {
    // Create container client
    const containerClient = await blobServiceClient.getContainerClient(
      containerName
    );

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Создание containerClient напрямую

Без пароля

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Unique container name
const timeStamp = Date.now();
const containerName = `test`;

async function main() {
  try {
    
    // create container client from DefaultAzureCredential
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      new DefaultAzureCredential()
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }


  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Ключ учетной записи

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

async function main() {
  try {
    // create container from ContainerClient
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      sharedKeyCredential
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }
    

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Маркер SAS

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables
require("dotenv").config();

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

// Container must exist prior to running this script
const containerName = `test`;

// SAS token must have LIST permissions on container that haven't expired
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;

// Create SAS URL
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}?${sasToken}`;

async function main() {
  try {
    // create container client from SAS token
    const containerClient = new ContainerClient(sasUrl);

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }   
    
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Пакет dotenv используется для чтения имени учетной .env записи хранения из файла. Этот файл не должен быть проверка в управление версиями.

Создание объекта BLOBClient

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

Список клиентов BLOB-объектов:

• BlobClient
• BlockBlobClient
• AppendBlobClient
• BlobLeaseClient
• PageBlobClient

Создание объекта BLOBClient из ContainerClient

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

// Create ContainerClient
const containerClient = new ContainerClient(
  `${baseUrl}/${containerName}`,
  sharedKeyCredential
);  

async function main() {
  try {
  
    // Create BlobClient object
    const blobClient = containerClient.getBlobClient(blobName);

    // do something with blobClient...
    const properties = await blobClient.getProperties();
    console.log(`Blob ${blobName} properties:`);

    // get BlockBlobClient from blobClient
    const blockBlobClient = blobClient.getBlockBlobClient();

    // do something with blockBlobClient...
    const downloadResponse = await blockBlobClient.download(0);

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Создание BLOBClient напрямую

Без пароля

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Container must exist prior to running this script
const containerName = `test`;

// Random blob name and contents
const timeStamp = Date.now();
const blobName = `${timeStamp}-my-blob.txt`;
const fileContentsAsString = "Hello there.";

async function main(){

  // Create a client that can authenticate with Azure Active Directory
  const client = new BlockBlobClient(
    `${baseUrl}/${containerName}/${blobName}`,
    new DefaultAzureCredential()
  );

  // Get file url - available before contents are uploaded
  console.log(`blob.url: ${client.url}`);

  // Upload file contents
  const result = await client.upload(fileContentsAsString, fileContentsAsString.length);

  // Get results
  return result;
}

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

/*

Response looks like this:

{
  etag: '"0x8DAD247F1F4896E"',
  lastModified: 2022-11-29T20:26:07.000Z,
  contentMD5: <Buffer 9d 6a 29 63 87 20 77 db 67 4a 27 a3 9c 49 2e 61>,
  clientRequestId: 'a07fdd1f-5937-44c7-984f-0699a48a05c0',
  requestId: '3580e726-201e-0045-1a30-0474f6000000',
  version: '2021-04-10',
  date: 2022-11-29T20:26:06.000Z,
  isServerEncrypted: true,
  'content-length': '0',
  server: 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0',
  'x-ms-content-crc64': 'BLv7vb1ONT8=',
  body: undefined
}
*/

Ключ учетной записи

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  BlockBlobClient,
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

const fileContentsAsString = "Hello there.";

async function main() {
  try {

    // create blob from BlockBlobClient
    const blockBlobClient = new BlockBlobClient(
      `${baseUrl}/${containerName}/${blobName}`,
      sharedKeyCredential
    );

    // Upload data to the blob  
    await blockBlobClient.upload(
      fileContentsAsString,
      fileContentsAsString.length
    );
    console.log(`blob ${blockBlobClient.url} created`);
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Маркер SAS

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// For development environment - include environment variables
require("dotenv").config();

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

// Container and blob must exist prior to running this script
// SAS token must have READ permissions on blob that haven't expired
const containerName = `test`;
const blobName = `my-text-file.txt`;

// Create SAS URL
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN;
const sasUrl = `https://${accountName}.blob.core.windows.net/${containerName}/${blobName}?${sasToken}`;

// Utility function to convert 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);
  });
}

async function main(){

  // Create a blob client from SAS token
  const client = new BlockBlobClient(sasUrl);

  // Get blob url
  console.log(`blob.url: ${client.url}`);

  // Download file contents
  const result = await client.download();
  const content = await streamToBuffer(result.readableStreamBody);

  // Get results
  return content.toString();
}

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

Пакет dotenv используется для чтения имени учетной .env записи хранения из файла. Этот файл не должен быть проверка в управление версиями.

См. также

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