إنشاء واستخدام رموز SAS المميزة للحساب مع Azure Blob Storage وJavaScript

مقالة
09/21/2023

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

تتوفر عينات قصاصات برمجية في GitHub في شكل ملفات Node.js قابلة للتشغيل.

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

رموز SAS المميزة للحساب

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

أفضل الممارسات لإنشاء الرمز المميز تتضمن الحد من الأذونات:

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

إضافة التبعيات المطلوبة إلى تطبيقك

تضمين التبعيات المطلوبة لإنشاء رمز SAS المميز للحاوية.

const { 
    BlobServiceClient, 
    generateAccountSASQueryParameters, 
    AccountSASPermissions, 
    AccountSASServices,
    AccountSASResourceTypes,
    StorageSharedKeyCredential,
    SASProtocol 
} = require('@azure/storage-blob');
require('dotenv').config()

الحصول على متغيرات البيئة لإنشاء بيانات اعتماد المفتاح المشترك

استخدام اسم حساب Blob Storage ومفتاحه لإنشاء StorageSharedKeyCredential. هذا المفتاح مطلوب لإنشاء رمز SAS المميز واستخدام رمز SAS المميز.

إنشاء StorageSharedKeyCredential باستخدام اسم حساب التخزين ومفتاح الحساب. ثم استخدم بيانات اعتماد StorageSharedKeyProfile لتهيئة BlobServiceClient.

const constants = {
    accountName: process.env.AZURE_STORAGE_ACCOUNT_NAME,
    accountKey: process.env.AZURE_STORAGE_ACCOUNT_KEY
};
const sharedKeyCredential = new StorageSharedKeyCredential(
    constants.accountName,
    constants.accountKey
);

شفرة متداولة لعملية غير متزامنة

تفترض نماذج القصاصات البرمجية المتبقية التعليمات البرمجية المتداولة غير المتزامنة التالية لـ Node.js.

async function main() {

    const sasToken = await createAccountSas();

    await useSasToken(sasToken);
}

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

إنشاء رمز SAS مميز

نظرًا لأنه يمكن استخدام هذا الرمز المميز مع الكائنات الثنائية كبيرة الحجم وقوائم الانتظار والجداول والملفات، فإن بعض الإعدادات تكن أكثر اتساعًا من خيارات الكائن الثنائي كبير الحجم فقط.

إنشاء عنصر الخيارات.

يتم تعريف نطاق قدرات رمز SAS المميز بواسطة AccountSASSignatureValues.

استخدم دوال المساعد التالية التي يوفرها SDK لإنشاء أنواع القيم الصحيحة للقيم:
- AccountSASServices.parse("btqf").toString():
  - ك: كائن ثنائي كبير الحجم
  - ج: جدول
  - ا: استعلام
  - م: ملف
- resourceTypes: AccountSASResourceTypes.parse("sco").toString()
  - خ: خدمة
  - ح: حاوية - مثل حاوية كائن ثنائي كبير الحجم أو جدول أو قائمة انتظار
  - ع: عنصر - كائن ثنائي كبير الحجم، صف، رسالة
- permissions: AccountSASPermissions.parse("rwdlacupi")
  - ق: قراءة
  - ك: كتابة
  - ح: حذف
  - إ: إدراج
  - ت: تصفية
  - إ: إضافة
  - إ: إنشاء
  - ت: تحديث
  - ا: الوصول إلى العلامة
  - ع: عملية - مثل معالجة الرسائل في قائمة انتظار
  - ث: نطاق نهج الثبات

مرر العنصر إلى دالة generateAccountSASQueryParameters، جنبًا إلى جنب مع SharedKeyCredential، لإنشاء رمز SAS المميز.

قبل إرجاع رمز SAS المميز، بادر بإيقاف محدد سلسلة الاستعلام مسبقًا، ?.

async function createAccountSas() {

    const sasOptions = {

        services: AccountSASServices.parse("btqf").toString(),          // blobs, tables, queues, files
        resourceTypes: AccountSASResourceTypes.parse("sco").toString(), // service, container, object
        permissions: AccountSASPermissions.parse("rwdlacupi"),          // permissions
        protocol: SASProtocol.Https,
        startsOn: new Date(),
        expiresOn: new Date(new Date().valueOf() + (10 * 60 * 1000)),   // 10 minutes
    };

    const sasToken = generateAccountSASQueryParameters(
        sasOptions,
        sharedKeyCredential 
    ).toString();

    console.log(`sasToken = '${sasToken}'\n`);

    // prepend sasToken with `?`
    return (sasToken[0] === '?') ? sasToken : `?${sasToken}`;
}

تأمين رمز SAS المميز حتى يتم استخدامه.

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

لاستخدام رمز SAS المميز للحساب، تحتاج إلى دمجه مع اسم الحساب لإنشاء URI. مرر URI لإنشاء blobServiceClient. بمجرد أن يكون لديك blobServiceClient، يمكنك استخدام هذا العميل للوصول إلى خدمة الكائن الثنائي كبير الحجم خاصتك.

// 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}`));

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

// 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 ملف. يجب عدم إيداع هذا الملف في عنصر تحكم المصدر.

مشاركة عبر