JavaScript için Azure Depolama Dosya Paylaşımı istemci kitaplığı

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ştur/Oku/Listele/Güncelle/Sil

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 kod
Paket (npm)
API Başvuru Belgeleri
Ürün belgeleri
Samples
Azure Depolama Dosyası REST API'lerini

Başlangıç Yapmak

Şu anda desteklenen ortamlar

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

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

Prerequisites

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ı

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.

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

N/A

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

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

Depolama hesabının kendisi, bir ShareServiceClient
Depolama hesabı içinde bir dosya paylaşımı ile temsil edilen ShareClient
örnekleriyle temsil edilen, dosya paylaşımında dizinlerin isteğe bağlı hiyerarşisi
Dosya paylaşımı içinde, boyutu en fazla 1 TiB olabilen ve birShareFileClient

Examples

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:

import * as AzureStorageFileShare from "@azure/storage-file-share";

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

import { ShareServiceClient, StorageSharedKeyCredential } from "@azure/storage-file-share";

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 ShareServiceClient statik yöntemini kullanarak bir fromConnectionString() örneği oluşturabilirsiniz. (Bağlantı dizesi azure portalından alınabilir.)

import { ShareServiceClient } from "@azure/storage-file-share";

const connectionString = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connectionString);

`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.)

import { StorageSharedKeyCredential, ShareServiceClient } from "@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.

import { ShareServiceClient } from "@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 ShareServiceClient.listShares() söz dizimi ile bu hesaptaki yineleyici paylaşımlarına for-await-of kullanın:

import { StorageSharedKeyCredential, ShareServiceClient } from "@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,
);

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

Alternatif olarak for-await-ofolmadan:

import { StorageSharedKeyCredential, ShareServiceClient } from "@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 shareIter = serviceClient.listShares();
let i = 1;
let { value, done } = await shareIter.next();
while (!done) {
  console.log(`Share ${i++}: ${value.name}`);
  ({ value, done } = await shareIter.next());
}

import { StorageSharedKeyCredential, ShareServiceClient } from "@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 = `newshare${+new Date()}`;
const shareClient = serviceClient.getShareClient(shareName);
await shareClient.create();
console.log(`Create share ${shareName} successfully`);

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

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

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

const content = "Hello World!";
const fileName = `newdirectory${+new Date()}`;
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`);

Dizin altındaki dosyaları ve dizinleri listeleme

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

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

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

Alternatif olarak for-await-ofkullanmadan:

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

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

Yinelemeyle ilgili eksiksiz bir örnek için lütfen samples/v12/typescript/src/listFilesAndDirectories.ts sayfasına bakın.

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

import { StorageSharedKeyCredential, ShareServiceClient } from "@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>";
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();
if (downloadFileResponse.readableStreamBody) {
  const buffer = await streamToBuffer(downloadFileResponse.readableStreamBody);
  console.log(`Downloaded file content: ${buffer.toString()}`);
}

// [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
async function streamToBuffer(readableStream: NodeJS.ReadableStream): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

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.

import { ShareServiceClient } from "@azure/storage-file-share";

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

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

const shareName = "<share name>";
const fileName = "<file name>";
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);
if (downloadFileResponse.blobBody) {
  console.log(`Downloaded file content: ${(await downloadFileResponse.blobBody).text()}`);
}

Basit ShareServiceClient senaryoların tam bir örneği samples/v12/typescript/src/shareSerivceClient.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

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

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.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-10-17