JavaScript için Azure Depolama Blobu istemci kitaplığı - sürüm 12.24.0

Makale
07/24/2024

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ıları Oluşturma/Listeleme/Silme
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

Anahtar bağlantıları

Başlarken

Şu anda desteklenen ortamlar

Node.js LTS sürümleri
Safari, Chrome, Edge ve Firefox'un en son sürümleri.

Daha fazla bilgi için bkz. destek ilkesi.

Önkoşullar

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
Paylaşılan Anahtar
paylaşılan erişim imzalarını

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.

Uyumluluk

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ğının ayrıntıları için lütfenpaketleme 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:

BlobServiceClient aracılığıyla kullanılan depolama hesabı
ContainerClient aracılığıyla kullanılan depolama hesabında kapsayıcı
BlobClient aracılığıyla kullanılan bir kapsayıcıda blob

Örnekler

Paket içeri aktarma
Blob hizmeti istemci oluşturma
Yeni kapsayıcı oluşturma
Kapsayıcıları listeleme
Verileri karşıya yükleyerek blob oluşturma
Kapsayıcı içindeki blobları listeleme
Blobu indirin ve dizeye (Node.js) dönüştürün
Blobu indirme ve dizeye dönüştürme (Tarayıcılar)

Paketi içeri aktarma

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

const AzureStorageBlob = require("@azure/storage-blob");

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

const { BlobServiceClient, StorageSharedKeyCredential } = require("@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.

`@azure/identity` paketinden `DefaultAzureCredential`

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

Kurulum : Başvuru - İstemci uygulamasından Azure Active Directory ile bloblara ve kuyruklara erişimi yetkilendirme - /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-portalda) yeni bir uygulama kaydetme - /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
- Bloblar ve kuyruklar için RBAC rolleri - /azure/storage/common/storage-auth-aad-rbac-portal.
- Azure portalında depolama hesabınıza gidin ve Access control (IAM) sekmesinden (azure-portaldaki depolama hesabınızın sol tarafındaki gezinti çubuğunda) kayıtlı AAD uygulamasına Depolama Blob Verileri Katkıda Bulunanı rolü atayın.
Ö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).

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@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 fromConnectionString() statik yöntemini kullanarak bir BlobServiceClient örneği oluşturabilirsiniz. (Bağlantı dizesi azure portalından alınabilir.) [YALNıZCA NODE.JS ÇALıŞMA ZAMANıNDA KULLANıLABILIR]

const { BlobServiceClient } = require("@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 StorageSharedKeyCredential içeren bir BlobServiceClient örneği oluşturursunuz. (Hesap adı ve hesap anahtarı azure portaldan alınabilir.) [YALNıZCA NODE.JS ÇALıŞMA ZAMANıNDA KULLANıLABILIR]

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

// Enter your storage account name and shared key
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.

const { BlobServiceClient } = require("@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.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  // 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);
}

main();

Kapsayıcıları listeleme

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

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

Alternatif olarak for-await-ofkullanmadan:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

Kapsayıcıları yinelemeye ilişkin eksiksiz bir örnek için bkz. samples/v12/typescript/src/listContainers.ts.

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

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

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

main();

Kapsayıcı içindeki blobları listeleme

Kapsayıcıları listelemeye benzer.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

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

main();

Blobları yinelemeyle ilgili eksiksiz bir örnek için bkz. samples/v12/typescript/src/listBlobsFlat.ts.

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

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";
const blobName = "<blob name>";

async function main() {
  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();
  const downloaded = (
    await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
  ).toString();
  console.log("Downloaded blob content:", downloaded);

  // [Node.js only] A helper method used to read 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);
    });
  }
}

main();

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.

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";

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

async function main() {
  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 downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
  console.log("Downloaded blob content", downloaded);

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob) {
    const fileReader = new FileReader();
    return new Promise((resolve, reject) => {
      fileReader.onloadend = (ev) => {
        resolve(ev.target.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

Basit senaryolara tam bir örnek samples/v12/typescript/src/sharedKeyAuth.tskonumundadır.

Sorun giderme

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, @azure/loggersetLogLevel çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Sonraki adımlar

Diğer kod örnekleri:

Katkıda

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.

Gösterimler

Aracılığıyla paylaş

JavaScript için Azure Depolama Blobu istemci kitaplığı - sürüm 12.24.0

Başlarken

Şu anda desteklenen ortamlar

Önkoşullar

Paketi yükleme

İstemcinin kimliğini doğrulama

Azure Active Directory

Uyumluluk

Web Çalışanları

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

Özellikler, arabirimler, sınıflar veya işlevler yalnızca Node.js

Özellikler, arabirimler, sınıflar veya işlevler yalnızca tarayıcılarda kullanılabilir

JavaScript Paketi

CORS

Temel kavramlar

Örnekler

Paketi içeri aktarma

Blob hizmeti istemcisini oluşturma

`@azure/identity` paketinden `DefaultAzureCredential`

bağlantı dizesini kullanma

`StorageSharedKeyCredential` ile

SAS Belirteci ile

Yeni kapsayıcı oluşturma

Kapsayıcıları listeleme

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

Kapsayıcı içindeki blobları listeleme

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

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

Sorun giderme

Sonraki adımlar

Katkıda

Ek kaynaklar

Aracılığıyla paylaş

JavaScript için Azure Depolama Blobu istemci kitaplığı - sürüm 12.24.0

Başlarken

Şu anda desteklenen ortamlar

Önkoşullar

Paketi yükleme

İstemcinin kimliğini doğrulama

Azure Active Directory

Uyumluluk

Web Çalışanları

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

Özellikler, arabirimler, sınıflar veya işlevler yalnızca Node.js

Özellikler, arabirimler, sınıflar veya işlevler yalnızca tarayıcılarda kullanılabilir

JavaScript Paketi

CORS

Temel kavramlar

Örnekler

Paketi içeri aktarma

Blob hizmeti istemcisini oluşturma

@azure/identity paketinden DefaultAzureCredential

bağlantı dizesini kullanma

StorageSharedKeyCredential ile

SAS Belirteci ile

Yeni kapsayıcı oluşturma

Kapsayıcıları listeleme

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

Kapsayıcı içindeki blobları listeleme

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

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

Sorun giderme

Sonraki adımlar

Katkıda

Ek kaynaklar

`@azure/identity` paketinden `DefaultAzureCredential`

`StorageSharedKeyCredential` ile