Aracılığıyla paylaş

JavaScript için Azure Depolama Blob istemci kitaplığı - sürüm 12.29.1

Azure Depolama Blobu, Microsoft'un bulut için nesne depolama çözümüdür. 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ımına uymayan verilerdir.

Bu proje, JavaScript'te Microsoft Azure Depolama Blob hizmeti kullanılmasını kolaylaştıran bir istemci kitaplığı sağlar.

Aşağıdakiler için bu paketteki istemci kitaplıklarını kullanın:

  • Blob Hizmeti Özelliklerini Alma/Ayarlama
  • Kapsayıcı Oluştur/Listele/Sil
  • Blok Blobları Oluşturma/Okuma/Listeleme/Güncelleştirme/Silme
  • Sayfa Blobları Oluşturma/Okuma/Listeleme/Güncelleştirme/Silme
  • Ekleme Bloblarını Oluşturma/Okuma/Listeleme/Güncelleştirme/Silme

Önemli bağlantılar

Başlangıç Yapmak

Şu anda desteklenen ortamlar

Daha fazla ayrıntı için destek politikamıza bakın.

Prerequisites

Paketi yükleme

JavaScript için Azure Depolama Blobu istemci kitaplığını yüklemenin tercih edilen yolu npm paket yöneticisini kullanmaktır. Terminal penceresine aşağıdakileri yazın:

npm install @azure/storage-blob

İstemcinin kimliğini doğrulama

Azure Depolama, kimlik doğrulaması için çeşitli yolları destekler. Azure Blob Depolama hizmetiyle etkileşim kurmak için bir Depolama istemcisi örneği oluşturmanız gerekir: örneğin, BlobServiceClient, ContainerClientveya BlobClient. Kimlik doğrulaması hakkında daha fazla bilgi edinmek için bkz. oluşturmak için örnekleri.

Azure Active Directory

Azure Blob Depolama hizmeti, API'lerine yönelik isteklerin kimliğini doğrulamak için Azure Active Directory kullanımını destekler. @azure/identity paketi, uygulamanızın bunu yapmak için kullanabileceği çeşitli kimlik bilgisi türleri sağlar. Başlamanıza yönelik diğer ayrıntılar ve örnekler için lütfen BENIOKU bölümüne bakın.

Compatibility

Bu kitaplık Node.js ve tarayıcılarla uyumludur ve LTS Node.js sürümlerine (>=8.16.0) ve Chrome, Firefox ve Edge'in en son sürümlerine göre doğrulanır.

Web Çalışanları

Bu kitaplık, belirli DOM nesnelerinin tarayıcıda kullanıldığında genel olarak kullanılabilir olmasını gerektirir ve bu, web çalışanlarının varsayılan olarak kullanılabilir hale getirmez. Bu kitaplığın web çalışanlarında çalışması için bunları çok doldurmanız gerekir.

Daha fazla bilgi için lütfen Web Çalışanları JS için Azure SDK'sını kullanmaya yönelik belgelerimize bakın

Bu kitaplık, web çalışanlarında kullanıldığında dış çok dolguların yüklenmesi gereken aşağıdaki DOM API'lerine bağlıdır:

Node.js ve tarayıcılar arasındaki farklar

Node.js ve tarayıcı çalışma zamanı arasında farklar vardır. Bu kitaplığı kullanmaya başlarken, veya "YALNIZCA NODE.JS ÇALıŞMA ZAMANıNDA KULLANıLABILIR" ile işaretlenmiş API'lere veya sınıflara dikkat edin.

  • Blob sıkıştırılmış verileri gzip veya deflate biçimde tutuyorsa ve içerik kodlaması buna göre ayarlandıysa, indirme davranışı Node.js ve tarayıcılar arasında farklıdır. Node.js depolama istemcilerinde blob sıkıştırılmış biçiminde indirilirken tarayıcılarda veriler sıkıştırılmış biçimde indirilir.
Özellikler, arabirimler, sınıflar veya işlevler yalnızca Node.js
  • Hesap adına ve hesap anahtarına göre Paylaşılan Anahtar Yetkilendirmesi
    • StorageSharedKeyCredential
  • Paylaşılan Erişim İmzası (SAS) oluşturma
    • generateAccountSASQueryParameters()
    • generateBlobSASQueryParameters()
  • Paralel karşıya yükleme ve indirme. BlockBlobClient.uploadData() hem Node.js hem de tarayıcılarda kullanılabilir olduğunu unutmayın.
    • BlockBlobClient.uploadFile()
    • BlockBlobClient.uploadStream()
    • BlobClient.downloadToBuffer()
    • BlobClient.downloadToFile()
Özellikler, arabirimler, sınıflar veya işlevler yalnızca tarayıcılarda kullanılabilir
  • Paralel karşıya yükleme ve indirme
    • BlockBlobClient.uploadBrowserData()

JavaScript Paketi

Bu istemci kitaplığını tarayıcıda kullanmak için önce bir paketleyici kullanmanız gerekir. Bunun nasıl yapılacağıyla ilgili ayrıntılar için lütfen paketleme belgelerimize bakın.

CORS

Tarayıcılar için geliştirmeniz gerekiyorsa depolama hesabınız için Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) kuralları ayarlamanız gerekir. Azure portalına ve Azure Depolama Gezgini'ne gidin, depolama hesabınızı bulun, blob/kuyruk/dosya/tablo hizmetleri için yeni CORS kuralları oluşturun.

Örneğin, hata ayıklama için aşağıdaki CORS ayarlarını oluşturabilirsiniz. Ancak lütfen üretim ortamındaki gereksinimlerinize göre ayarları dikkatli bir şekilde özelleştirin.

  • İzin verilen çıkış noktaları: *
  • İzin verilen fiiller: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
  • İzin verilen üst bilgiler: *
  • Kullanıma sunulan üst bilgiler: *
  • Maksimum yaş (saniye): 86400

Temel kavramlar

Blob depolama şu şekilde tasarlanmıştır:

  • Görüntüleri veya belgeleri doğrudan bir tarayıcıya sunma.
  • Dağıtılmış erişim için dosyaları depolama.
  • Video ve ses akışı.
  • Günlük dosyalarına yazma.
  • Yedekleme ve geri yükleme, olağanüstü durum kurtarma ve arşivleme için verileri depolama.
  • Verileri şirket içinde veya Azure'da barındırılan bir hizmet tarafından analiz için depolama.

Blob depolama üç tür kaynak sunar:

  • aracılığıyla kullanılan depolama hesabıBlobServiceClient
  • Depolama hesabında aracılığıyla kullanılan bir kapsayıcıContainerClient
  • aracılığıyla kullanılan bir kapsayıcıdaki blobBlobClient

Examples

Paketi içeri aktarma

İstemcileri kullanmak için paketi dosyanıza aktarın:

import * as AzureStorageBlob from "@azure/storage-blob";

Alternatif olarak, yalnızca ihtiyacınız olan türleri seçmeli olarak içeri aktarın:

import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";

Blob hizmeti istemcisini oluşturma

BlobServiceClient blob hizmetinin URL'sini ve erişim kimlik bilgilerini gerektirir. ayrıca isteğe bağlı olarak options parametresindeki bazı ayarları kabul eder.

DefaultAzureCredential paketinden @azure/identity

bir BlobServiceClient örneği oluşturmanın önerilen yolu

Kurulum : Referans - Bir istemci uygulamasından Azure Active Directory ile bloblara ve kuyruklara erişimi yetkilendirme - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

  • Yeni bir AAD uygulaması kaydedin ve oturum açan kullanıcı adına Azure Depolama'ya erişim izinleri verin

    • Azure Active Directory'ye (azure-portal'da) yeni bir uygulama kaydedin - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
    • API permissions bölümünde Add a permission ve Microsoft APIsseçin.
    • Azure Storage seçin, user_impersonation yanındaki onay kutusunu seçin ve ardından Add permissionsöğesine tıklayın. Bu, uygulamanın oturum açmış kullanıcı adına Azure Depolama'ya erişmesine olanak tanır.

  • Azure Portal'da RBAC ile Azure Blob verilerine erişim izni verme

  • Örnek için ortam kurulumu

    • AAD Uygulamanızın genel bakış sayfasında CLIENT ID ve TENANT IDnot edin. "Sertifikalar & Gizli Diziler" sekmesinde bir gizli dizi oluşturun ve bunu not edin.
    • Örneği başarıyla yürütmek için ortam değişkenleri olarak AZURE_TENANT_ID, AZURE_CLIENT_ID AZURE_CLIENT_SECRET sahip olduğunuzdan emin olun (process.env'yi kullanabilir).
import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential,
);

Bu yöntemi kullanarak tam bir örnek için azure ad kimlik doğrulaması örneği bakın.

[Not - Yukarıdaki adımlar yalnızca Node.jsiçindir]

bağlantı dizesini kullanma

Alternatif olarak, bağımsız değişken olarak tam bağlantı dizesiyle BlobServiceClient statik yöntemini kullanarak bir fromConnectionString() örneği oluşturabilirsiniz. (Bağlantı dizesi azure portalından alınabilir.) [YALNıZCA NODE.JS ÇALıŞMA ZAMANıNDA KULLANıLABILIR]

import { BlobServiceClient } from "@azure/storage-blob";

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

StorageSharedKeyCredential ile

Alternatif olarak, hesap adını ve hesap anahtarını bağımsız değişken olarak geçirerek BlobServiceClient içeren bir StorageSharedKeyCredential örneği oluşturursunuz. (Hesap adı ve hesap anahtarı azure portaldan alınabilir.) [YALNıZCA NODE.JS ÇALıŞMA ZAMANıNDA KULLANıLABILIR]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential,
);

SAS Belirteci ile

Ayrıca, paylaşılan erişim imzalarıyla (SAS) bir BlobServiceClient örneği oluşturabilirsiniz. SAS belirtecini Azure Portal'dan alabilir veya generateAccountSASQueryParameters()kullanarak oluşturabilirsiniz.

import { BlobServiceClient } from "@azure/storage-blob";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net?${sas}`);

Yeni kapsayıcı oluşturma

Kapsayıcı istemci örneğini almak için BlobServiceClient.getContainerClient() kullanın ve ardından yeni bir kapsayıcı kaynağı oluşturun.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

// Create a container
const containerName = `newcontainer${new Date().getTime()}`;
const containerClient = blobServiceClient.getContainerClient(containerName);
const createContainerResponse = await containerClient.create();
console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);

Kapsayıcıları listeleme

Kapsayıcıları yinelemek için yeni BlobServiceClient.listContainers() söz dizimi ile for-await-of işlevini kullanın:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const containers = blobServiceClient.listContainers();
for await (const container of containers) {
  console.log(`Container ${i++}: ${container.name}`);
}

Alternatif olarak for-await-ofkullanmadan:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iter = blobServiceClient.listContainers();
let { value, done } = await iter.next();
while (!done) {
  console.log(`Container ${i++}: ${value.name}`);
  ({ value, done } = await iter.next());
}

Ayrıca sayfalandırma, byPage()aracılığıyla listeleme için de desteklenir:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const page of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  for (const container of page.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

Yineleme kapsayıcıları hakkında tam bir örnek için lütfen samples/v12/typescript/src/listContainers.ts sayfasına bakın.

Verileri karşıya yükleyerek blob oluşturma

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

const content = "Hello world!";
const blobName = `newblob ${+new Date()}`;
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(
  `Upload block blob ${blobName} successfully with request ID: ${uploadBlobResponse.requestId}`,
);

Kapsayıcı içindeki blobları listeleme

Kapsayıcıları listelemeye benzer.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

let i = 1;
const blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

Blobları yinelemeyle ilgili tam bir örnek için lütfen bkz samples/v12/typescript/src/listBlobsFlat.ts.

Blobu indirin ve dizeye dönüştürün (Node.js)

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
const downloadBlockBlobResponse = await blobClient.download();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

Blobu indirin ve dizeye dönüştürün (Tarayıcılar).

Bu kitaplığı tarayıcıda kullanma hakkında daha fazla bilgi için lütfen JavaScript Paketi bölümüne bakın.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blobClient.download();
const blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

Basit senaryoların tam bir örneği samples/v12/typescript/src/sharedKeyAuth.ts adresindedir.

Troubleshooting

Günlüğe kaydetmeyi etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın. Alternatif olarak, setLogLevel@azure/logger çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Sonraki Adımlar

Diğer kod örnekleri:

Contributing

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

Ayrıca, depolama kitaplıkları için test ortamını ayarlama hakkında ek bilgi için Depolama'ya özgü kılavuz bakın.

  • Last updated on