Aracılığıyla paylaş

Azure Blob Depolama ve TypeScript kullanmaya başlama

  • Makale

Bu makalede JavaScript için Azure Blob Depolama istemci kitaplığını kullanarak Azure Blob Depolama nasıl bağlanabileceğiniz gösterilmektedir. Bağlandıktan sonra kodunuz Blob Depolama hizmetinin kapsayıcıları, blobları ve özellikleri üzerinde çalışabilir.

Paket (npm) | API başvurusu | Kitaplık kaynak kodu | Geri Bildirim Ver

Önkoşullar

Projenizi ayarlama

  1. Bir komut istemi açın ve proje klasörünüzde değiştirin. Klasör adınızla değiştirin YOUR-DIRECTORY :

    cd YOUR-DIRECTORY

  2. Dizininizde henüz bir package.json dosya yoksa, dosyayı oluşturmak için projeyi başlatın:

    npm init -y

  3. TypeScript türleri dahil olmak üzere TypeScript'i ve JavaScript için Azure Blob Depolama istemci kitaplığını yükleyin:

    npm install typescript @azure/storage-blob

  4. Microsoft Entra ID kullanarak parolasız bağlantılar kullanmak istiyorsanız JavaScript için Azure Identity istemci kitaplığını yükleyin:

    npm install @azure/identity

Erişimi yetkilendirme ve Blob Depolama'ya bağlanma

Microsoft Entra ID, bağlantı kimliğini (yönetilen kimlik) yöneterek en güvenli bağlantıyı sağlar. Bu parolasız işlevsellik, kodda depolanan gizli dizileri (anahtarlar veya bağlantı dizesi) gerektirmeyen bir uygulama geliştirmenizi sağlar.

Azure buluta kimlik erişimini ayarlama

Azure'a parola olmadan bağlanmak için bir Azure kimliği ayarlamanız veya mevcut bir kimliği kullanmanız gerekir. Kimlik ayarlandıktan sonra, kimliğe uygun rolleri atadığınızdan emin olun.

Microsoft Entra Id ile parolasız erişimi yetkilendirmek için bir Azure kimlik bilgisi kullanmanız gerekir. İhtiyacınız olan kimlik bilgisi türü, uygulamanızın nerede çalıştığına bağlıdır. Bu tabloyu kılavuz olarak kullanın.

Ortam Metot
Geliştirme ortamı Visual Studio Code
Geliştirme ortamı Hizmet sorumlusu
Azure’da barındırılan uygulamalar Azure tarafından barındırılan uygulamalar kurulumu
Şirket içinde Şirket içi uygulama kurulumu

Depolama hesabı rollerini ayarlama

Depolama kaynağınızın bağlanmayı planladığınız kimlik kaynağına aşağıdaki Azure RBAC rollerinden birinin veya daha fazlasının atanmış olması gerekir. Önceki adımda oluşturduğunuz her kimlik için Azure Depolama rollerini ayarlayın: Azure bulutu, yerel geliştirme, şirket içi.

Kurulumu tamamladıktan sonra her kimliğin uygun rollerden en az birine ihtiyacı vardır:

  • Veri erişim rolü- örneğin:

    • Depolama Blob Verileri Okuyucusu
    • Depolama Blobu Veri Katılımcısı

  • Kaynak rolü:

    • Okuyucu
    • Katkıda Bulunan

Uygulamanızı derleme

Uygulamanızı oluştururken kodunuz öncelikli olarak üç tür kaynakla etkileşim kurar:

  • Azure Depolama verileriniz için benzersiz üst düzey ad alanı olan depolama hesabı.
  • Depolama hesabınızdaki blob verilerini düzenleyen kapsayıcılar.
  • Metin ve ikili veriler gibi yapılandırılmamış verileri depolayan bloblar.

Aşağıdaki diyagramda bu kaynaklar arasındaki ilişki gösterilmektedir.

Blob depolama mimarisi diyagramı

Her kaynak türü bir veya daha fazla ilişkili JavaScript istemcisiyle temsil edilir:

Sınıf Açıklama
BlobServiceClient Depolama hesabınız için Blob Depolama uç noktasını temsil eder.
ContainerClient Azure Depolama kapsayıcılarını ve bloblarını işlemenize olanak tanır.
BlobClient Azure Depolama bloblarını işlemenize olanak tanır.

BlobServiceClient nesnesi oluşturma

BlobServiceClient nesnesi SDK'daki en üstteki nesnedir. Bu istemci hizmeti, kapsayıcıları ve blobları işlemenizi sağlar.

Azure depolama hesabı kimlik rolleriniz ve yerel ortamınız ayarlandıktan sonra paketi içeren @azure/identity bir TypeScript dosyası oluşturun. Blob Depolama'ya parolasız bağlantılar uygulamak için DefaultAzureCredential gibi bir kimlik bilgisi oluşturun. BlobServiceClient nesnesiyle kimlik doğrulaması yapmak için bu kimlik bilgilerini kullanın.

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

Paket dotenv , depolama hesabınızın adını bir .env dosyadan okumak için kullanılır. Bu dosya kaynak denetiminde denetlenmemelidir. DefaultAzureCredential kurulumunuzun bir parçası olarak yerel bir hizmet sorumlusu kullanırsanız, bu kimlik bilgisi için tüm güvenlik bilgileri de dosyaya .env gider.

Uygulamayı Azure dışında çalışan sunuculara ve istemcilere dağıtmayı planlıyorsanız, gereksinimlerinizi karşılayan kimlik bilgilerinden birini oluşturun.

ContainerClient nesnesi oluşturma

ContainerClient nesnesini BlobServiceClient'dan veya doğrudan oluşturabilirsiniz.

BlobServiceClient'dan ContainerClient nesnesi oluşturma

BlobServiceClient'dan ContainerClient nesnesini oluşturun.

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

Doğrudan ContainerClient oluşturma

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

Paket dotenv , depolama hesabınızın adını bir .env dosyadan okumak için kullanılır. Bu dosya kaynak denetiminde denetlenmemelidir.

BlobClient nesnesi oluşturma

Aşağıda listelenen BlobClient nesnelerinden herhangi birini bir ContainerClient'dan veya doğrudan oluşturabilirsiniz.

Blob istemcilerinin listesi:

ContainerClient'dan BlobClient nesnesi oluşturma

// 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'u doğrudan oluşturma

// 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
}
*/

Paket dotenv , depolama hesabınızın adını bir .env dosyadan okumak için kullanılır. Bu dosya kaynak denetiminde denetlenmemelidir.

Ayrıca bkz.