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

Azure Dosyalar, bulutta endüstri standardı Sunucu İleti Bloğu (SMB) protokolü aracılığıyla erişilebilen tam olarak yönetilen dosya paylaşımları sunar. Azure dosya paylaşımları, Windows, Linux ve macOS'un bulut veya şirket içi dağıtımları tarafından eşzamanlı olarak bağlanabilir. Ayrıca Azure dosya paylaşımları, verilerin kullanıldığı yerin yakınında hızlı erişim için Azure Dosya Eşitleme ile Windows Sunucularında önbelleğe alınabiliyor.

Bu proje, JavaScript'te Microsoft Azure Dosya Depolama hizmetini kullanımı kolaylaştıran bir istemci kitaplığı sağlar.

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

• Dosya Hizmeti Özelliklerini Alma/Ayarlama
• Dosya Paylaşımlarını Oluştur/Listele/Sil
• Dosya Dizinlerini Oluştur/Listele/Sil
• Dosya Oluşturma/Okuma/Listeleme/Güncelleştirme/Silme

Not: Bu paket daha önce @azure/storage-fileadı altında yayımlanmıştı. Azure Depolama Dosyaları DataLake için yaklaşan yeni paketle daha iyi uyumlu hale getirmek ve Azure'da dosyalarla çalışmak için tutarlı bir API kümesi sağlamak üzere @azure/storage-file-share olarak yeniden adlandırıldı.

Önemli bağlantılar:

• Kaynak kodu
• Paketi (npm)
• API Başvuru Belgeleri
• Ürün belgeleri
• Örnekleri
• Azure Depolama Dosyası REST API'lerini

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

• Azure aboneliği
• Depolama Hesabı

Paketi yükleme

JavaScript için Azure Dosya Depolama 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-file-share

İstemcinin kimliğini doğrulama

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

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

• document
• DOMParser
• Node
• XMLSerializer

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.

• Bir dosya sıkıştırılmış verileri gzip veya deflate biçiminde 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 istemcileri dosyayı sıkıştırılmış biçiminde indirirken tarayıcılarda veriler sıkıştırılmış biçimde indirilir.

Aşağıdaki ö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()
  • generateFileSASQueryParameters()
• Paralel karşıya yükleme ve indirme. ShareFileClient.uploadData() hem Node.js hem de tarayıcılarda kullanılabilir olduğunu unutmayın.
  • ShareFileClient.uploadFile()
  • ShareFileClient.uploadStream()
  • ShareFileClient.downloadToBuffer()
  • ShareFileClient.downloadToFile()

Aşağıdaki özellikler, arabirimler, sınıflar veya işlevler yalnızca tarayıcılarda kullanılabilir

YOK

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

Aşağıdaki bileşenler ve ilgili istemci kitaplıkları Azure Depolama Dosya Paylaşımı hizmetini oluşturur:

• depolama hesabı kendisini, bir ShareServiceClient temsil eder
• Depolama hesabı içinde bir ShareClient temsil edilen dosya paylaşımı
• örnekleriyle temsil edilen, dosya paylaşımında dizinlerin isteğe bağlı hiyerarşisi
• Dosya paylaşımında bir temsil edilen boyutu 1 TiB'a kadar olabilen bir dosyası

Örnekler

• Paket içeri aktarma
• Paylaşım hizmeti istemcisi oluşturma
• Hesap liste paylaşımlarını
• Yeni paylaşım ve dizin oluşturma
• Azure dosyası oluşturup bu dosyaya yükleyin
• Dizin altında dosya ve dizinleri listeleme
• Dosyayı indirin ve dizeye (Node.js) dönüştürün
• Bir dosyayı indirin ve bir dizeye (Tarayıcılar) dönüştürün

Paketi içeri aktarma

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

const AzureStorageFileShare = require("@azure/storage-file-share");

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

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

Paylaşım hizmeti istemcisini oluşturma

ShareServiceClient, dosya paylaşımı hizmetinin URL'sini ve erişim kimlik bilgilerini gerektirir. ayrıca isteğe bağlı olarak options parametresindeki bazı ayarları kabul eder.

bağlantı dizesini kullanma

Alternatif olarak, bağımsız değişken olarak tam bağlantı dizesiyle fromConnectionString() statik yöntemini kullanarak bir ShareServiceClient örneği oluşturabilirsiniz. (Bağlantı dizesi azure portalından alınabilir.)

const { ShareServiceClient } = require("@azure/storage-file-share");

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

StorageSharedKeyCredential ile

Hesap adınız ve hesap anahtarınız ile bir StorageSharedKeyCredential geçirin. (Hesap adı ve hesap anahtarı azure portaldan alınabilir.)

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

// 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 credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  // When using AnonymousCredential, following url should include a valid SAS
  `https://${account}.file.core.windows.net`,
  credential
);

SAS Belirteci ile

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

const { ShareServiceClient } = require("@azure/storage-file-share");

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

const serviceClientWithSAS = new ShareServiceClient(
  `https://${account}.file.core.windows.net${sas}`
);

Hesaptaki paylaşımları listeleme

Yeni for-await-of söz dizimi ile bu hesaptaki yineleyici paylaşımlarına ShareServiceClient.listShares() kullanın:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  let shareIter = serviceClient.listShares();
  let i = 1;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

Alternatif olarak for-await-ofolmadan:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  let shareIter = serviceClient.listShares();
  let i = 1;
  let shareItem = await shareIter.next();
  while (!shareItem.done) {
    console.log(`Share ${i++}: ${shareItem.value.name}`);
    shareItem = await shareIter.next();
  }
}

main();

Yeni bir paylaşım ve dizin oluşturma

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  const shareName = `newshare${new Date().getTime()}`;
  const shareClient = serviceClient.getShareClient(shareName);
  await shareClient.create();
  console.log(`Create share ${shareName} successfully`);

  const directoryName = `newdirectory${new Date().getTime()}`;
  const directoryClient = shareClient.getDirectoryClient(directoryName);
  await directoryClient.create();
  console.log(`Create directory ${directoryName} successfully`);
}

main();

Azure dosyası oluşturma ve ardından dosyaya yükleme

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const content = "Hello World!";
  const fileName = "newfile" + new Date().getTime();
  const fileClient = directoryClient.getFileClient(fileName);
  await fileClient.create(content.length);
  console.log(`Create file ${fileName} successfully`);

  // Upload file range
  await fileClient.uploadRange(content, 0, content.length);
  console.log(`Upload file range "${content}" to ${fileName} successfully`);
}

main();

Dizin altındaki dosyaları ve dizinleri listeleme

Yeni for-await-of söz dizimi ile dosyalar ve dizinler üzerinde yineleyici DirectoryClient.listFilesAndDirectories() kullanın. kind özelliği, yinelemenin dizin mi yoksa dosya mı olduğunu belirlemek için kullanılabilir.

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  let dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  for await (const item of dirIter) {
    if (item.kind === "directory") {
      console.log(`${i} - directory\t: ${item.name}`);
    } else {
      console.log(`${i} - file\t: ${item.name}`);
    }
    i++;
  }
}

main();

Alternatif olarak for-await-ofkullanmadan:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  let dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  let item = await dirIter.next();
  while (!item.done) {
    if (item.value.kind === "directory") {
      console.log(`${i} - directory\t: ${item.value.name}`);
    } else {
      console.log(`${i} - file\t: ${item.value.name}`);
    }
    item = await dirIter.next();
  }
}

main();

Yinelemeyle ilgili eksiksiz bir örnek için bkz. samples/v12/typescript/src/listFilesAndDirectories.ts.

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

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const fileName = "<file name>";

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

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadFileResponse.readableStreamBody
  const downloadFileResponse = await fileClient.download();
  console.log(
    `Downloaded file content: ${(
      await streamToBuffer(downloadFileResponse.readableStreamBody)
    ).toString()}`
  );
}

main();

Dosyayı indirme ve dizeye dönüştürme (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 { ShareServiceClient } = require("@azure/storage-file-share");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const shareName = "<share name>";
const fileName = "<file name>";

const serviceClient = new ShareServiceClient(`https://${account}.file.core.windows.net${sas}`);

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadFileResponse.blobBody
  const downloadFileResponse = await fileClient.download(0);
  console.log(
    `Downloaded file content: ${await blobToString(await downloadFileResponse.blobBody)}`
  );
}

// [Browser 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 ShareServiceClient senaryolarına tam bir örnek samples/v12/typescript/src/shareSerivceClient.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

• Dosya Paylaşımı Depolama Örnekleri (JavaScript)
• Dosya Paylaşımı Depolama Örnekleri (TypeScript)
• Dosya Paylaşımı Depolama Test Çalışmalarını

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.