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

Makale
01/10/2024

Azure Depolama Blobu, Microsoft'un bulut için nesne depolama çözümüdür. Blob depolama, çok miktarda yapılandırılmamış veriyi 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.

Bu proje, Microsoft Azure Depolama Blob hizmetini tüketmeyi kolaylaştıran JavaScript'te bir istemci kitaplığı sağlar.

Bu paketteki istemci kitaplıklarını kullanarak:

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

Anahtar bağlantılar

Başlarken

Şu anda desteklenen ortamlar

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

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

Ö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: BlobServiceClient, ContainerClientveya BlobClient örneğin. Kimlik doğrulaması hakkında daha fazla bilgi edinmek için oluşturma BlobServiceClientörneklerine bakın.

Azure Active Directory
Paylaşılan Anahtar
Paylaşılan erişim imzaları

Azure Active Directory

Azure Blob Depolama hizmeti, API'lerinde isteklerin kimliğini doğrulamak için Azure Active Directory kullanımını destekler. Paket, @azure/identity uygulamanızın bunu yapmak için kullanabileceği çeşitli kimlik bilgileri türleri sağlar. Başlamanıza yönelik diğer ayrıntılar ve örnekler için @azure/identitybkz. BENİOKU.

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 da 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ında JS için Azure SDK'sını kullanma belgelerimize bakın

Bu kitaplık, web çalışanlarında kullanıldığında dış polifilllerin 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 , "ONLY AVAILABLE IN NODE.JS RUNTIME" veya "ONLY AVAILABLE IN BROWSERS" ile işaretlenmiş API'lere veya sınıflara dikkat edin.

Blob sıkıştırılmış verileri gzip veya deflate biçiminde barındırıyorsa 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. Hem Node.js hem de tarayıcılarda kullanılabildiğini BlockBlobClient.uploadData() 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ü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 ve Azure Depolama Gezgini 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

Önemli kavramlar

Blob depolama şunlar için tasarlanmıştır:

Görüntülerin veya belgelerin doğrudan bir tarayıcıya sunulması.
Dağıtılan erişim için dosyaların depolanması.
Video ve ses akışları.
Günlük dosyalarına yazma.
Yedekleme ve geri yükleme, olağanüstü durum kurtarma ve arşivleme için verilerin depolanması.
Şirket içi veya Azure’da barındırılan bir hizmetle analiz için verilerin depolanması.

Blob depolama üç tür kaynak sunar:

Aracılığıyla kullanılan depolama hesabıBlobServiceClient
Aracılığıyla kullanılan depolama hesabındaki bir kapsayıcıContainerClient
Aracılığıyla kullanılan kapsayıcıdaki blobBlobClient

Örnekler

Paketi içeri aktarma
Blob hizmeti istemcisini 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 indirme ve dizeye dönüştürme (Node.js)
Blob 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 parametresindeki options bazı ayarları kabul eder.

paketten ile `DefaultAzureCredential@azure/identity`

Örneği oluşturmak için önerilen yol BlobServiceClient

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çmış kullanıcı adına Azure Depolama'ya erişim izinleri verin
- Azure Active Directory'ye yeni bir uygulama kaydetme (azure-portalda) - /azure/active-directory/develop/quickstart-register-app
- API permissions bölümünde öğesini ve Add a permission öğesini seçinMicrosoft APIs.
- öğesinin yanındaki user_impersonation onay kutusunu seçip Azure Storage seçin ve ardından öğesine tıklayınAdd permissions. Bu, uygulamanın oturum açmış kullanıcı adına Azure Depolama'ya erişmesine olanak tanır.
Azure Portalda RBAC ile Azure Blob verilerine erişim 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 kayıtlı AAD uygulamasına Access control (IAM) (azure-portaldaki depolama hesabınızın sol tarafındaki gezinti çubuğunda) Depolama Blob Verileri Katkıda Bulunanı rolü atayın.
Örnek için ortam kurulumu
- AAD Uygulamanızın genel bakış sayfasında ve TENANT IDdeğerlerini CLIENT ID not 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ğine bakın.

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

bağlantı dizesi kullanma

Alternatif olarak, bağımsız değişken olarak tam bağlantı dizesi statik yöntemi kullanarak fromConnectionString() bir BlobServiceClient örneği oluşturabilirsiniz. (bağlantı dizesi Azure portaldan 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);

Ile `StorageSharedKeyCredential`

Alternatif olarak, hesap adını ve hesap anahtarını bağımsız değişken olarak geçirerek ile StorageSharedKeyCredential bir örneği BlobServiceClient oluşturursunuz. (Hesap adı ve hesap anahtarı azure portalından 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 kullanarak generateAccountSASQueryParameters()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 ve ardından yeni bir kapsayıcı kaynağı oluşturmak için kullanın BlobServiceClient.getContainerClient() .

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

Yeni for-await-of söz dizimi ile kapsayıcıları yinelemek için işlevini kullanınBlobServiceClient.listContainers():

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, kullanmadan for-await-of:

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

Buna ek olarak, sayfalandırma aracılığıyla listeleme için de byPage()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ı yinelemeyle ilgili 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 indirme ve dizeye dönüştürme (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 senaryoların tam bir örneği samples/v12/typescript/src/sharedKeyAuth.ts adresindedir.

Sorun giderme

Günlüğe kaydetmenin etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir:

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

setLogLevel("info");

Sonraki adımlar

Diğer kod örnekleri:

Katkıda bulunma

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.

Ayrıca depolama kitaplıkları için test ortamını ayarlama hakkında ek bilgi için Depolamaya özgü kılavuza bakın.

İzlenimler

JavaScript için Azure Depolama Blobu istemci kitaplığı - sürüm 12.17.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

Önemli kavramlar

Örnekler

Paketi içeri aktarma

Blob hizmeti istemcisini oluşturma

paketten ile `DefaultAzureCredential@azure/identity`

bağlantı dizesi kullanma

Ile `StorageSharedKeyCredential`

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 indirme ve dizeye dönüştürme (Node.js)

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

Sorun giderme

Sonraki adımlar

Katkıda bulunma

Geri Bildirim

Ek kaynaklar

JavaScript için Azure Depolama Blobu istemci kitaplığı - sürüm 12.17.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

Önemli kavramlar

Örnekler

Paketi içeri aktarma

Blob hizmeti istemcisini oluşturma

paketten ile DefaultAzureCredential@azure/identity

bağlantı dizesi kullanma

Ile StorageSharedKeyCredential

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 indirme ve dizeye dönüştürme (Node.js)

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

Sorun giderme

Sonraki adımlar

Katkıda bulunma

Geri Bildirim

Ek kaynaklar

paketten ile `DefaultAzureCredential@azure/identity`

Ile `StorageSharedKeyCredential`