Aracılığıyla paylaş

Hızlı Başlangıç: TypeScript ile Node.js için Azure Blob Depolama istemci kitaplığı

Blobları ve kapsayıcıları yönetmek için TypeScript ile Node.js için Azure Blob Depolama istemci kitaplığını kullanmaya başlayın.

Bu makalede, paketi yüklemek için adımları izleyin ve temel görevler için örnek kodu deneyin.

API başvurusu | Kitaplık kaynak kodu | Paketi (npm)Örnekler |

Önkoşullar

Ayarlama

Bu bölümde, Node.js için Azure Blob Depolama istemci kitaplığıyla çalışacak bir proje hazırlama işleminde size yol gösterir.

Node.js projesini oluşturma

blob-quickstart adlı bir TypeScript uygulaması oluşturun.

  1. Konsol penceresinde (cmd, PowerShell veya Bash gibi) proje için yeni bir dizin oluşturun:

    mkdir blob-quickstart

  2. Yeni oluşturulan blob-quickstart dizinine geçin:

    cd blob-quickstart

  3. package.json dosyası oluşturun:

    npm init -y

  4. Projeyi Visual Studio Code'da açın:

    code .

  5. TypeScript ile ESM'yi desteklemek üzere aşağıdaki özellikleri eklemek için package.json dosyasını düzenleyin:

    "type": "module",

Paketleri yükleme

Proje dizininden komutunu kullanarak npm install aşağıdaki paketleri yükleyin.

  1. Azure Depolama npm paketini yükleyin:

    npm install @azure/storage-blob

  2. Bu hızlı başlangıçta kullanılan diğer bağımlılıkları yükleyin:

    npm install uuid dotenv @types/node @types/uuid

  3. Proje dizininde aşağıdaki içeriklere sahip bir tsconfig.json dosya oluşturun.

    {
    "compilerOptions": {
      "target": "es2022",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
      "module": "ESNext",                                /* Specify what module code is generated. */
      "moduleResolution": "node",                     /* Specify how TypeScript looks up a file from a given module specifier. */
      "outDir": "dist",                                   /* Specify an output folder for all emitted files. */
      "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
      "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
      "strict": true,                                      /* Enable all strict type-checking options. */
      "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
    }
  }

Nesne modeli

Azure Blob depolama, çok büyük miktarlarda yapılandırılmamış verileri depolamak için iyileştirilmiştir. Yapılandırılmamış veriler, metin veya ikili veriler gibi belirli bir veri modeline veya tanıma bağlı olmayan verilerdir. Blob depolama üç tür kaynak sunar:

  • Depolama hesabı
  • Depolama hesabındaki bir kapsayıcı
  • Kapsayıcıdaki bir blob

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

Blob depolama mimarisinin diyagramı.

Bu kaynaklarla etkileşime geçmek için aşağıdaki JavaScript sınıflarını kullanın:

  • BlobServiceClient: sınıfı, BlobServiceClient Azure Depolama kaynaklarını ve blob kapsayıcılarını işlemenize olanak tanır.
  • ContainerClient: sınıfı, ContainerClient Azure Depolama kapsayıcılarını ve bloblarını işlemenize olanak tanır.
  • BlobClient: sınıfı, BlobClient Azure Depolama bloblarını işlemenize olanak tanır.

Kod örnekleri

Bu örnek kod parçacıkları, JavaScript için Azure Blob Depolama istemci kitaplığıyla aşağıdaki görevlerin nasıl yapılacağını gösterir:

Örnek kod GitHub'da da kullanılabilir.

Azure'da kimlik doğrulaması ve blob verilerine erişim yetkisi verme

Azure Blob Depolama uygulama istekleri yetkilendirilmelidir. DefaultAzureCredential Azure Identity istemci kitaplığı tarafından sağlanan sınıfı kullanmak, Blob Depolama da dahil olmak üzere kodunuzdaki Azure hizmetlerine parolasız bağlantılar uygulamak için önerilen yaklaşımdır.

Ayrıca, hesap erişim anahtarını kullanarak istekleri Azure Blob Depolama yetkilendirmeniz de gerekir. Ancak bu yaklaşım dikkatli kullanılmalıdır. Geliştiriciler, erişim anahtarını güvenli olmayan bir konumda asla kullanıma sunmamak için dikkatli olmalıdır. Erişim anahtarına sahip olan herkes, depolama hesabına yönelik istekleri yetkilendirebiliyor ve tüm verilere etkin bir şekilde erişim sahibi oluyor. DefaultAzureCredential parolasız kimlik doğrulamasına izin vermek için hesap anahtarı üzerinde gelişmiş yönetim ve güvenlik avantajları sunar. Her iki seçenek de aşağıdaki örnekte gösterilmiştir.

DefaultAzureCredential birden çok kimlik doğrulama yöntemini destekler ve çalışma zamanında hangi yöntemin kullanılacağını belirler. Bu yaklaşım, uygulamanızın ortama özgü kod uygulamadan farklı ortamlarda (yerel ve üretim) farklı kimlik doğrulama yöntemleri kullanmasını sağlar.

Kimlik bilgilerinin arandığı DefaultAzureCredential sıra ve konumlar Azure Kimlik kitaplığına genel bakış sayfasında bulunabilir.

Örneğin, uygulamanız yerel olarak geliştirme yaparken Azure CLI oturum açma kimlik bilgilerinizi kullanarak kimlik doğrulaması yapabilir. Uygulamanız, Azure'a dağıtıldıktan sonra yönetilen kimliği kullanabilir. Bu geçiş için kod değişikliği gerekmez.

Microsoft Entra kullanıcı hesabınıza rol atama

Yerel olarak geliştirme yaparken blob verilerine erişen kullanıcı hesabının doğru izinlere sahip olduğundan emin olun. Blob verilerini okumak ve yazmak için Depolama Blob Verileri Katkıda Bulunanı gerekir. Kendinize bu rolü atamak için Kullanıcı Erişimi Yöneticisi rolüne veya Microsoft.Authorization/roleAssignments/write eylemini içeren başka bir role atanmalısınız. Azure portalı, Azure CLI veya Azure PowerShell'i kullanarak kullanıcıya Azure RBAC rolleri atayabilirsiniz. Depolama Blob Verisi Katkıda Bulunan rolü hakkında daha fazla bilgi için Depolama Blob Verisi Katkıda Bulunan sayfasına bakın. Rol atamaları için kullanılabilir kapsamlar hakkında daha fazla bilgi için bkz. Azure RBAC kapsamını anlama.

Bu senaryoda, En Az Ayrıcalık İlkesi'ni izlemek için depolama hesabı kapsamındaki kullanıcı hesabınıza izinler atayacaksınız. Bu uygulama kullanıcılara yalnızca gereken minimum izinleri verir ve daha güvenli üretim ortamları oluşturur.

Aşağıdaki örnek, depolama hesabınızdaki blob verilerine hem okuma hem de yazma erişimi sağlayan Depolama Blob Verileri Katkıda Bulunanı rolünü kullanıcı hesabınıza atar.

Önemli

Çoğu durumda rol atamasının Azure'a yayılması bir veya iki dakika sürer, ancak nadir durumlarda sekiz dakikaya kadar sürebilir. Kodunuzu ilk kez çalıştırdığınızda kimlik doğrulama hataları alıyorsanız, birkaç dakika bekleyin ve yeniden deneyin.

  1. Azure portalında ana arama çubuğunu veya sol gezintiyi kullanarak depolama hesabınızı bulun.

  2. Depolama hesabına genel bakış sayfasında sol taraftaki menüden Erişim denetimi (IAM) öğesini seçin.

  3. Erişim denetimi (IAM) sayfasında Rol atamaları sekmesini seçin.

  4. Üst menüden + Ekle'yi seçin ve ardından açılan menüden Rol ataması ekle'yi seçin.

    Rol atamayı gösteren ekran görüntüsü.

  5. Sonuçları istenen role göre filtrelemek için arama kutusunu kullanın. Bu örnek için Depolama Blobu Veri Katkıda Bulunanı'nı arayın ve eşleşen sonucu seçin ve ardından İleri'yi seçin.

  6. Erişim ata'nın altında Kullanıcı, grup veya hizmet sorumlusu'na tıklayın ve ardından + Üye seç'e tıklayın.

  7. İletişim kutusunda Microsoft Entra kullanıcı adınızı (genellikle user@domain e-posta adresiniz) arayın ve iletişim kutusunun alt kısmındaki Seç'i seçin.

  8. Son sayfaya gitmek için Gözden geçir + ata'yı seçin ve ardından işlemi tamamlamak için Gözden geçir + yeniden ata'yı seçin.

DefaultAzureCredential kullanarak oturum açın ve uygulama kodunuzu Azure'a bağlayın

Aşağıdaki adımları kullanarak depolama hesabınızdaki verilere erişimi yetkileyebilirsiniz:

  1. Depolama hesabınızda rolü atadığınız Microsoft Entra hesabıyla kimliğinizin doğrulanmış olduğundan emin olun. Azure CLI, Visual Studio Code veya Azure PowerShell aracılığıyla kimlik doğrulaması yapabilirsiniz.

    Aşağıdaki komutu kullanarak Azure CLI aracılığıyla Azure'da oturum açın:

    az login

  2. kullanmak DefaultAzureCredentialiçin @azure\identity paketinin yüklendiğinden ve sınıfın içeri aktarıldığından emin olun:

    import { DefaultAzureCredential } from '@azure/identity';

  3. Bu kodu bloğun try içine ekleyin. Kod yerel iş istasyonunuzda çalıştığında, DefaultAzureCredential Azure'da kimlik doğrulaması yapmak için oturum açtığınız öncelikli aracın geliştirici kimlik bilgilerini kullanır. Bu araçlara örnek olarak Azure CLI veya Visual Studio Code verilebilir.

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

// Add `Storage Blob Data Contributor` role assignment to the identity
const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

  4. Dosyadaki veya ortamınızın değişkenlerindeki AZURE_STORAGE_ACCOUNT_NAME depolama hesabı adını .envgüncelleştirdiğinden emin olun. Depolama hesabı adı, Azure portalının genel bakış sayfasında bulunabilir.

    Depolama hesabı adını bulmayı gösteren ekran görüntüsü.

    Not

    Azure'a dağıtıldığında, Azure'da çalışan bir uygulamadan Azure Depolama'ya yönelik istekleri yetkilendirmek için aynı kod kullanılabilir. Ancak Azure'daki uygulamanızda yönetilen kimliği etkinleştirmeniz gerekir. Ardından depolama hesabınızı bu yönetilen kimliğin bağlanmasına izin verecek şekilde yapılandırın. Azure hizmetleri arasında bu bağlantıyı yapılandırma hakkında ayrıntılı yönergeler için Bkz. Azure tarafından barındırılan uygulamalardan kimlik doğrulama öğreticisi.

Kapsayıcı oluşturma

Depolama hesabında yeni bir kapsayıcı oluşturun. Aşağıdaki kod örneği bir BlobServiceClient nesnesi alır ve kapsayıcıya başvuru almak için getContainerClient yöntemini çağırır. Ardından kod, depolama hesabınızda kapsayıcıyı oluşturmak için create yöntemini çağırır.

Bu kodu bloğun try sonuna ekleyin:

  const containerName = 'quickstart' + uuidv4();

  console.log('\nCreating container...');
  console.log('\t', containerName);

  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse: ContainerCreateResponse = await containerClient.create();
  console.log(
    `Container was created successfully.\n\trequestId:${createContainerResponse.requestId}\n\tURL: ${containerClient.url}`
  );

Kapsayıcı oluşturma hakkında daha fazla bilgi edinmek ve daha fazla kod örneği keşfetmek için bkz . JavaScript ile blob kapsayıcısı oluşturma.

Önemli

Kapsayıcı adlarının küçük harfle yazılması gerekir. Kapsayıcıları ve blobları adlandırma hakkında daha fazla bilgi için bkz. Kapsayıcıları, Blobları ve Meta Verileri Adlandırma ve Bunlara Başvurma.

Blobları kapsayıcıya yükleme

Kapsayıcıya bir blob yükleyin. Aşağıdaki kod, Kapsayıcı oluşturma bölümünden ContainerClient üzerindeki getBlockBlobClient yöntemini çağırarak bir BlockBlobClient nesnesine başvuru alır.

Kod, karşıya yükleme yöntemini çağırarak metin dizesi verilerini bloba yükler .

Bu kodu bloğun try sonuna ekleyin:

  const blobName = 'quickstart' + uuidv4(); + '.txt';
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  console.log(
    `\nUploading to Azure storage as blob\n\tname: ${blobName}:\n\tURL: ${blockBlobClient.url}`
  );

  const data = 'Hello, World!';
  const uploadBlobResponse: BlockBlobUploadResponse = await blockBlobClient.upload(data, data.length);
  console.log(
    `Blob was uploaded successfully. requestId: ${uploadBlobResponse.requestId}`
  );

Blobları karşıya yükleme hakkında daha fazla bilgi edinmek ve daha fazla kod örneği keşfetmek için bkz . JavaScript ile blob yükleme.

Kapsayıcıdaki blobları listeleme

Kapsayıcı içindeki blobları listeleme. Aşağıdaki kod listBlobsFlat yöntemini çağırır. Bu durumda kapsayıcıda yalnızca bir blob olduğundan listeleme işlemi yalnızca bu blobu döndürür.

Bu kodu bloğun try sonuna ekleyin:

  console.log('\nListing blobs...');

  for await (const blob of containerClient.listBlobsFlat()) {
    const tempBlockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blob.name);

    console.log(
      `\n\tname: ${blob.name}\n\tURL: ${tempBlockBlobClient.url}\n`
    );
  }

Blobları listeleme hakkında daha fazla bilgi edinmek ve daha fazla kod örneği keşfetmek için bkz . JavaScript ile blobları listeleme.

Blob’ları indirme

Blobu indirin ve içeriğini görüntüleyin. Aşağıdaki kod blobu indirmek için indirme yöntemini çağırır.

Bu kodu bloğun try sonuna ekleyin:

  const offset = 0;         // start at beginning
  const length = undefined; // read all

  const downloadBlockBlobResponse: BlobDownloadResponseParsed = await blockBlobClient.download(offset, length);
  console.log('\nDownloaded blob content...');
  console.log(
    '\t',
    await streamToText(downloadBlockBlobResponse.readableStreamBody as NodeJS.ReadableStream)
  );

Aşağıdaki kod, içeriği görüntülemek için bir akışı bir dizeye geri dönüştürür.

İşlevden sonramainekleyin:

// Convert stream to text
async function streamToText(readable: NodeJS.ReadableStream): Promise<string> {
  readable.setEncoding('utf8');
  let data = '';
  for await (const chunk of readable) {
    data += chunk;
  }
  return data;
}

Blobları indirme hakkında daha fazla bilgi edinmek ve daha fazla kod örneği keşfetmek için bkz . JavaScript ile blob indirme.

Kapsayıcı silme

Kapsayıcıyı ve kapsayıcı içindeki tüm blobları silin. Aşağıdaki kod, delete yöntemini kullanarak kapsayıcının tamamını kaldırarak uygulama tarafından oluşturulan kaynakları temizler.

Bu kodu bloğun try sonuna ekleyin:

  console.log('\nDeleting container...');

  const deleteContainerResponse: ContainerDeleteResponse = await containerClient.delete();
  console.log(
    'Container was deleted successfully. requestId: ',
    deleteContainerResponse.requestId
  );

Kapsayıcı silme hakkında daha fazla bilgi edinmek ve daha fazla kod örneği keşfetmek için bkz . JavaScript ile blob kapsayıcısını silme ve geri yükleme.

Kodu çalıştırma

  1. Visual Studio Code terminalinden uygulamayı oluşturun.

    tsc

  2. Uygulamayı çalıştırma.

    node dist/index.js

  3. Uygulamanın çıkışı aşağıdaki örneğe benzer:

    Azure Blob storage - JavaScript quickstart sample

Creating container...
    quickstart4a0780c0-fb72-11e9-b7b9-b387d3c488da

Uploading to Azure Storage as blob:
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Listing blobs...
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Downloaded blob content...
    Hello, World!

Deleting container...
Done

Hata ayıklayıcınızdaki kodda ilerleyin ve işlem boyunca Azure portalınızı denetleyin. Kapsayıcının oluşturulup oluşturulmadığını denetleyin. Kapsayıcının içindeki blobu açabilir ve içeriğini görüntüleyebilirsiniz.

Kaynakları temizleme

  1. Bu hızlı başlangıcı tamamladığınızda dizini silin blob-quickstart .
  2. Azure Depolama kaynağınızı kullanmayı bitirdiyseniz Depolama kaynağını kaldırmak için Azure CLI'yı kullanın.

Sonraki adım

JavaScript ve TypeScript için Azure Depolama örnekleri ve geliştirici kılavuzları

  • Last updated on