Создание и использование маркеров SAS для учетной записи с помощью Хранилища BLOB-объектов Azure и JavaScript

• .NET
• Java
• JavaScript
• Python

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

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

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

Маркеры SAS для учетной записи

Маркер SAS для учетной записи — это один из типов маркера SAS, которые предоставляются службой хранилища Azure для делегирования доступа. Маркер SAS для учетной записи предоставляет доступ к службе хранилища Azure. Этот маркер ограничивает доступ в строгом соответствии с параметрами, указанными при его создании. Поскольку любой пользователь с таким маркером может использовать его для доступа к учетной записи хранения, необходимо включать в маркер SAS наиболее строгий набор разрешений, который минимально необходим для выполнения требуемых задач.

Рекомендации по созданию маркеров включают ограничение разрешений:

• Службы: большой двоичный объект, файл, очередь, таблица
• Типы ресурсов: служба, контейнер или объект
• Разрешения на создание, чтение, запись, обновление и удаление

Добавление обязательных зависимостей в приложение

Включите обязательные зависимости для создания маркера SAS для учетной записи.

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

Получение переменных среды для создания учетных данных общего ключа

Используйте ключ и имя учетной записи Хранилища BLOB-объектов для создания объекта StorageSharedKeyCredential. Этот ключ необходим для создания и использования маркера SAS.

Создайте объект StorageSharedKeyCredential с помощью имени учетной записи хранения и ключа учетной записи. Затем используйте StorageSharedKeyCredential для инициализации 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

Так как этот маркер можно использовать с большими двоичными объектами, очередями, таблицами и файлами, некоторые его параметры относятся не только к большим двоичным объектам.

1. Создайте объект options.

   Область возможностей маркера SAS определяется значением AccountSASSignatureValues.

   Пакет SDK предоставляет следующие вспомогательные функции, которые позволяют создать для значений правильные типы значений:

   • AccountSASServices.parse("btqf").toString():
     • b: blob (BLOB-объект)
     • t: table (таблица)
     • q: query (запрос)
     • f: file (файл)
   • resourceTypes: AccountSASResourceTypes.parse("sco").toString()
     • s: service (служба)
     • c: container (контейнер), например очередь, таблица или контейнер BLOB-объектов
     • o: object (объект) — BLOB-объект, запись, сообщение
   • permissions: AccountSASPermissions.parse("rwdlacupi")
     • r: read (чтение)
     • w: write (запись)
     • d: delete (удаление)
     • l: list (список)
     • f: filter (фильтр)
     • a: add (добавление)
     • c: create (создание)
     • u: update (обновление)
     • t: tag access (доступ к тегам)
     • p: process (процесс), например, обработка сообщений в очереди
     • i: set immutability policy (настройка политики неизменяемости)

2. Передайте этот объект в функцию 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}`;
   }
   

3. Защищайте маркер SAS, когда он не используется.

Использование службы BLOB-объектов с маркером SAS для учетной записи

BlobServiceClient

Чтобы применить маркер SAS для учетной записи, создайте на его основе универсальный код ресурса (URI), добавив имя учетной записи. Передайте этот URI для создания blobServiceClient. Получив клиент blobServiceClient, вы сможете использовать его для доступа к службе BLOB-объектов.

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

ContainerClient

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

BlobClient

// 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 записи хранения из файла. Этот файл не должен быть проверка в управление версиями.

См. также

• Типы маркеров SAS
• Как работает подписанный URL-адрес
• Справочник по API
• Исходный код библиотеки
• Обратная связь