Aracılığıyla paylaş

JavaScript için Azure Depolama Dosyası Data Lake istemci kitaplığı - sürüm 12.28.1

Azure Data Lake Storage (ADLS), geliştiricilerin, veri bilimcilerinin ve analistlerin her boyutta, şekilde ve hızda veri depolamasını ve platformlar ile diller arasında her türlü işleme ve analiz gerçekleştirmesini kolaylaştırmak için gereken tüm özellikleri içerir. Toplu iş, akış ve etkileşimli analizlerle çalışmaya başlamayı hızlandırırken tüm verilerinizi alma ve depolama karmaşıklıklarını ortadan kaldırır.

Bu proje, JavaScript'te Microsoft Azure Storage Data Lake 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 Sistemleri Oluşturma/Listeleme/Silme
  • Yolları, Dizinleri ve Dosyaları Oluşturma/Okuma/Listeleme/Güncelleştirme/Silme

Anahtar 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 Storage Data Lake 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-datalake

İstemcinin kimliğini doğrulama

Azure Depolama, kimlik doğrulaması için çeşitli yolları destekler. Azure Data Lake Storage hizmetiyle etkileşim kurmak için örneğin DataLakeServiceClient, DataLakeFileSystemClientveya DataLakePathClient bir Depolama istemcisi örneği oluşturmanız gerekir. Kimlik doğrulaması hakkında daha fazla bilgi edinmek için bkz. oluşturmak için örnekleri.

Azure Active Directory

Azure Data Lake Storage 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.

  • 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.
Ö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()
    • generateDataLakeSASQueryParameters()
  • Paralel karşıya yükleme ve indirme. DataLakeFileClient.upload() hem Node.js hem de tarayıcılarda kullanılabilir olduğunu unutmayın.
    • DataLakeFileClient.uploadFile()
    • DataLakeFileClient.uploadStream()
    • DataLakeFileClient.readToBuffer()
    • DataLakeFileClient.readToFile()
Ö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

Dikkat: Data Lake şu anda blob hizmeti için CORS ayarlarını paylaşıyor.

Temel kavramlar

Azure Data Lake Storage 2. Nesil, şu şekilde tasarlanmıştır:

  • Yüzlerce gigabit aktarım hızı sağlarken birden çok petabayt bilgi sunma
  • Çok büyük miktarda veriyi kolayca yönetmenize olanak sağlar

DataLake Storage 2. Nesil'in Temel Özellikleri şunlardır:

  • Hadoop uyumlu erişim
  • Süper posix izinleri kümesi
  • Düşük maliyetli depolama kapasitesi ve işlemler açısından uygun maliyetli
  • Büyük veri analizi için iyileştirilmiş sürücü

Data Lake Storage 2. Nesil'in temel bir parçası, Blob depolamaya hiyerarşik ad alanı eklenmesidir. Hiyerarşik ad alanı, verimli veri erişimi için nesneleri/dosyaları dizin hiyerarşisinde düzenler.

Geçmişte bulut tabanlı analizler performans, yönetim ve güvenlik alanlarından ödün vermek zorunda kalmıştı. Data Lake Storage 2. Nesil, bu yönlerin her birini aşağıdaki yollarla ele aldı:

  • Analiz önkoşulu olarak verileri kopyalamanız veya dönüştürmeniz gerekmediğinden performans iyileştirildi. Hiyerarşik ad alanı, dizin yönetimi işlemlerinin performansını büyük ölçüde iyileştirir ve bu da genel iş performansını artırır.
  • Dizinler ve alt dizinler aracılığıyla dosyaları düzenleyip işleyebildiğiniz için yönetim daha kolaydır.
  • Dizinler veya tek tek dosyalar üzerinde POSIX izinleri tanımlayabildiğiniz için güvenlik zorunlu kılınabilir.
  • Data Lake Storage 2. Nesil, düşük maliyetli Azure Blob depolamanın üzerine kurulu olduğundan maliyet verimliliği mümkün hale getirilmiştir. Ek özellikler, Azure'da büyük veri analizi çalıştırmak için toplam sahip olma maliyetini daha da düşürür.

Data Lake storage üç tür kaynak sunar:

  • aracılığıyla kullanılan depolama hesabıDataLakeServiceClient
  • Depolama hesabında kullanılan bir dosya sistemiDataLakeFileSystemClient
  • veya aracılığıyla DataLakeDirectoryClient kullanılan bir dosya sistemindeki yolDataLakeFileClient
Azure DataLake 2. Nesil Blob
Filesystem Container
Yol (Dosya veya Dizin) Blob

Not: Bu istemci kitaplığı yalnızca hiyerarşik ad alanı (HNS) etkinleştirilmiş depolama hesaplarını destekler.

Examples

Paketi içeri aktarma

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

import * as AzureStorageDataLake from "@azure/storage-file-datalake";

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

import { DataLakeServiceClient, StorageSharedKeyCredential } from "@azure/storage-file-datalake";

Data Lake Service istemcisini oluşturma

DataLakeServiceClient data lake 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 DataLakeServiceClient örneği oluşturmanın önerilen yolu

Notice. Azure Data Lake şu anda AAD OAuth kimlik doğrulaması sırasında "Depolama Blobu Veri Sahibi" gibi blobla ilgili rolleri yeniden kullanır.

Kurulum : Referans - Bir istemci uygulamasından Azure Active Directory ile bloblara (veri gölü) ve kuyruklara erişim yetkisi verin - https://learn.microsoft.com/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 (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 Data Lake 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 { DataLakeServiceClient } from "@azure/storage-file-datalake";

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

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.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 DataLakeServiceClient 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 { DataLakeServiceClient } from "@azure/storage-file-datalake";

const connectionString = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connectionString);

StorageSharedKeyCredential ile

Alternatif olarak, hesap adını ve hesap anahtarını bağımsız değişken olarak geçirerek DataLakeServiceClient 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, DataLakeServiceClient } from "@azure/storage-file-datalake";

// 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 datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  sharedKeyCredential,
);

SAS Belirteci ile

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

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const serviceClientWithSAS = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`,
);

Yeni dosya sistemi oluşturma

Dosya sistemi istemci örneğini almak için DataLakeServiceClient.getFileSystemClient() kullanın ve ardından yeni bir dosya sistemi kaynağı oluşturun.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

// Create a file system
const fileSystemName = `newfilesystem${new Date().getTime()}`;
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const createResponse = await fileSystemClient.create();
console.log(`Create file system ${fileSystemName} successfully`, createResponse.requestId);

Dosya sistemlerini listeleme

Yeni DataLakeServiceClient.listFileSystems() söz dizimi ile dosya sistemlerini yinelemek için for-await-of işlevini kullanın:

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
for await (const fileSystem of fileSystems) {
  console.log(`File system ${i++}: ${fileSystem.name}`);
}

Alternatif olarak for-await-ofkullanmadan:

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
let { value, done } = await fileSystems.next();
while (!done) {
  console.log(`File system ${i++}: ${value.name}`);
  ({ value, done } = await fileSystems.next());
}

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

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const response of datalakeServiceClient.listFileSystems().byPage({ maxPageSize: 20 })) {
  if (response.fileSystemItems) {
    for (const fileSystem of response.fileSystemItems) {
      console.log(`File System ${i++}: ${fileSystem.name}`);
    }
  }
}

Dizin oluşturma ve silme

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const directoryClient = fileSystemClient.getDirectoryClient("directory");
await directoryClient.create();
await directoryClient.delete();

Dosya oluşturma

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

const content = "Hello world!";
const fileName = `newfile${+new Date()}`;
const fileClient = fileSystemClient.getFileClient(fileName);
await fileClient.create();
await fileClient.append(content, 0, content.length);
await fileClient.flush(content.length);
console.log(`Create and upload file ${fileName} successfully`);

Dosya sistemi içindeki yolları listeleme

Dosya sistemlerini listelemeye benzer.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

let i = 1;
const paths = fileSystemClient.listPaths();
for await (const path of paths) {
  console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
}

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

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const fileClient = fileSystemClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadResponse.readableStreamBody
const downloadResponse = await fileClient.read();
if (downloadResponse.readableStreamBody) {
  const downloaded = await streamToBuffer(downloadResponse.readableStreamBody);
  console.log("Downloaded file content:", downloaded.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)

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const account = "<account>";
const sas = "<sas token>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`,
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const fileClient = fileSystemClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In browsers, get downloaded data by accessing downloadResponse.contentAsBlob
const downloadResponse = await fileClient.read();
if (downloadResponse.contentAsBlob) {
  const blob = await downloadResponse.contentAsBlob;
  const downloaded = await blob.text();
  console.log(`Downloaded file content ${downloaded}`);
}

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:

  • DataLake Depolama Örneklerini (JavaScript)
  • DataLake Depolama Örneklerini (TypeScript)
  • DataLake 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.

  • Last updated on