مشاركة عبر

بدء استخدام Azure Blob Storage وTypeScript

  • مقالة

توضح هذه المقالة كيفية الاتصال ب Azure Blob Storage باستخدام مكتبة عميل Azure Blob Storage ل JavaScript. بمجرد الاتصال، تستطيع التعليمة البرمجية الخاصة بك العمل على الحاويات وميزات خدمة الكائنات الثنائية كبيرة الحجم.

حزمة (npm) | API مرجع | مكتبة التعليمات البرمجية | المصدر تقديم الملاحظات

المتطلبات الأساسية

إعداد مشروعك

  1. افتح موجه الأوامر وقم بالتغيير إلى مجلد المشروع. تغيير YOUR-DIRECTORY إلى اسم المجلد الخاص بك:

    cd YOUR-DIRECTORY

  2. إذا لم يكن لديك ملف package.json بالفعل في الدليل، فقم بتهيئة المشروع لإنشاء الملف:

    npm init -y

  3. تثبيت TypeScript ومكتبة عميل Azure Blob Storage ل JavaScript مع تضمين أنواع TypeScript:

    npm install typescript @azure/storage-blob

  4. إذا كنت ترغب في استخدام اتصالات بدون كلمة مرور باستخدام معرف Microsoft Entra، فقم بتثبيت مكتبة عميل Azure Identity ل JavaScript:

    npm install @azure/identity

تخويل الوصول والاتصال ب Blob Storage

يوفر معرف Microsoft Entra الاتصال الأكثر أمانا من خلال إدارة هوية الاتصال (الهوية المدارة). تسمح لك هذه الوظيفة بدون كلمة مرور بتطوير تطبيق لا يتطلب أي أسرار (مفاتيح أو سلسلة الاتصال) مخزنة في التعليمات البرمجية.

إعداد الوصول إلى الهوية إلى سحابة Azure

للاتصال ب Azure بدون كلمات مرور، تحتاج إلى إعداد هوية Azure أو استخدام هوية موجودة. بمجرد إعداد الهوية، تأكد من تعيين الأدوار المناسبة للهوية.

لتخويل الوصول بدون كلمة مرور باستخدام معرف Microsoft Entra، ستحتاج إلى استخدام بيانات اعتماد Azure. يعتمد نوع بيانات الاعتماد التي تحتاج لها على مكان تشغيل التطبيق. استخدم هذا الجدول كدليل.

البيئة الأسلوب
بيئة المطور Visual Studio Code
بيئة المطور كيان الخدمة
التطبيقات المستضافة من Azure إعداد التطبيقات المستضافة من Azure
محلي إعداد التطبيق المحلي

إعداد أدوار حساب التخزين

يجب أن يكون لمورد التخزين الخاص بك دور واحد أو أكثر من أدوار Azure RBAC التالية المعينة لمورد الهوية الذي تخطط للاتصال به. قم بإعداد أدوار Azure Storage لكل هوية قمت بإنشائها في الخطوة السابقة: سحابة Azure، والتطوير المحلي، المحلي.

بعد إكمال الإعداد، تحتاج كل هوية إلى واحد على الأقل من الأدوار المناسبة:

  • دور الوصول إلى البيانات - مثل:

    • قارئ بيانات للبيانات الثنائية الكبيرة للتخزين
    • المساهم في بيانات مخزن البيانات الثنائية الكبيرة

  • دور المورد - مثل:

    • القارئ
    • المساهم

إنشاء التطبيق الخاص بك

في أثناء إنشاء التطبيق الخاص بك، سوف تتفاعل التعليمات البرمجية الخاصة بك في المقام الأول مع ثلاثة أنواع من الموارد:

  • حساب التخزين وهو بمثابة مساحة اسم فريدة عالية المستوى لبيانات Azure Storage.
  • الحاويات، التي تنظم بيانات النقطة في حساب التخزين الخاص بك.
  • الكائنات الثنائية كبيرة الحجم، التي تخزن البيانات غير المهيكلة مثل النص والبيانات الثنائية.

يعرض الرسم التخطيطي التالي العلاقة بين هذه الموارد.

رسم تخطيطي لبنية تخزين الكائن الثنائي كبير الحجم

يمثل عملاء JavaScript كل أنواع الموارد:

الفصل ‏‏الوصف
BlobServiceClient يمثل نقطة نهاية Blob Storage لحساب التخزين الخاص بك.
ContainerClient يسمح لك بمعالجة حاويات Azure Storage وحاويات الكائنات الثنائية كبيرة الحجم الخاصة بها.
عميل الكائن الثنائي كبير الحجم يسمح لك بالتحكم في كائنات Azure Storage الثنائية الكبيرة.

إنشاء كائن BlobServiceClient

عنصر BlobServiceClient هو العنصر الأهم في SDK. يسمح لك هذا العميل بالتلاعب بالخدمة والحاويات وكائن ثنائي كبير الحجم.

بمجرد إعداد أدوار هوية حساب تخزين Azure والبيئة المحلية الخاصة بك، قم بإنشاء ملف TypeScript الذي يتضمن الحزمة @azure/identity . إنشاء بيانات اعتماد، مثل DefaultAzureCredential، لتنفيذ اتصالات بدون كلمة مرور إلى Blob Storage. استخدم بيانات الاعتماد هذه للمصادقة مع كائن 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 ملف. يجب عدم إيداع هذا الملف في عنصر تحكم المصدر.

(راجع أيضًا )