Share via

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

  • Статья

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

Исходный | код | библиотеки пакета (npm)API |

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

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

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

    cd YOUR-DIRECTORY

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

    npm init -y

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

    npm install typescript @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-объекты, которые хранят неструктурированные данные, такие как текстовые и двоичные данные.

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

Diagram of Blob storage architecture

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

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

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

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

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

// connect-with-default-azure-credential.js
// You must set up RBAC for your identity with one of the following roles:
// - Storage Blob Data Reader
// - Storage Blob Data Contributor
import { DefaultAzureCredential } from '@azure/identity';
import { BlobServiceClient } from '@azure/storage-blob';
import * as dotenv from 'dotenv';
dotenv.config();

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
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 = 'my-container';
  const blobName = 'my-blob';

  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
  const downloadResult = await blobClient.downloadToFile(fileName);

  if (downloadResult.errorCode) throw Error(downloadResult.errorCode);

  console.log(
    `${fileName} downloaded ${downloadResult.contentType}, isCurrentVersion: ${downloadResult.isCurrentVersion}`
  );
}

main()
  .then(() => console.log(`success`))
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.message);
    }
  });

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

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

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

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

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

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

// Azure Storage dependency
import {
  BlobServiceClient,
  StorageSharedKeyCredential
} from '@azure/storage-blob';

// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();

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

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY as string;
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(): Promise<void> {
  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({
      includeMetadata: true,
      includeSnapshots: false,
      includeTags: true,
      includeVersions: false,
      prefix: ''
    })) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`success`))
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.message);
    }
  });

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

// Azure Storage dependency
import { ContainerClient } from '@azure/storage-blob';

// Azure authentication for credential dependency
import { DefaultAzureCredential } from '@azure/identity';

// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
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 = `my-container`;

async function main(): Promise<void> {
  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({
      includeMetadata: true,
      includeSnapshots: false,
      includeTags: true,
      includeVersions: false,
      prefix: ''
    })) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`success`))
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.message);
    }
  });

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

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

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

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

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

// Azure Storage dependency
import {
  BlobClient,
  BlobDownloadHeaders,
  BlobGetPropertiesHeaders,
  BlobGetPropertiesResponse,
  BlockBlobClient,
  ContainerClient
} from '@azure/storage-blob';

// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
import { getContainerClientFromDefaultAzureCredential } from './auth-get-client';
dotenv.config();

const containerName = `my-container`;
const containerClient: ContainerClient =
  getContainerClientFromDefaultAzureCredential(containerName);

const blobName = `my-blob`;

async function main(containerClient: ContainerClient): Promise<void> {
  // Create BlobClient object
  const blobClient: BlobClient = containerClient.getBlobClient(blobName);

  // do something with blobClient...
  const properties: BlobGetPropertiesHeaders = await blobClient.getProperties();
  if (properties.errorCode) throw Error(properties.errorCode);

  console.log(`Blob ${blobName} properties:`);

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

  // do something with blockBlobClient...
  const downloadResponse: BlobDownloadHeaders = await blockBlobClient.download(
    0
  );
  if (downloadResponse.errorCode) throw Error(downloadResponse.errorCode);
}

main(containerClient)
  .then(() => console.log(`success`))
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.message);
    }
  });

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

// Azure Storage dependency
import {
  BlockBlobClient,
  BlockBlobUploadHeaders,
  BlockBlobUploadResponse
} from '@azure/storage-blob';
import { getBlockBlobClientFromDefaultAzureCredential } from './auth-get-client';

// For development environment - include environment variables from .env
import * as dotenv from 'dotenv';
dotenv.config();

// Container must exist prior to running this script
const containerName = `my-container`;

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

const blockBlobClient: BlockBlobClient =
  getBlockBlobClientFromDefaultAzureCredential(containerName, blobName);

async function main(
  blockBlobClient: BlockBlobClient
): Promise<BlockBlobUploadHeaders> {
  // Get file url - available before contents are uploaded
  console.log(`blob.url: ${blockBlobClient.url}`);

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

  if (result.errorCode) throw Error(result.errorCode);

  // Get results
  return result;
}

main(blockBlobClient)
  .then((result) => {
    console.log(result);
    console.log(`success`);
  })
  .catch((err: unknown) => {
    if (err instanceof Error) {
      console.log(err.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
}
*/

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

См. также