Aracılığıyla paylaş

Öğretici: TypeScript ile azure depolama blob'larına görüntü yükleme

Bu öğreticide, kimlik bilgilerini açığa çıkarmadan bir tarayıcıdan doğrudan Azure Blob Depolama'ya dosya yükleme işlemi gösterilmektedir. Güvenli, anahtarsız kimlik doğrulaması için Paylaşılan Erişim İmzası (SAS) belirteçleri ve Yönetilen Kimlik ile Vale Anahtarı desenini uygulamak için TypeScript kullanacaksınız.

Örnek uygulama şunları içerir:

  • Zaman sınırlı SAS belirteçleri oluşturan bir Fastify API'si
  • Dosyaları doğrudan Azure Depolama'ya yükleyen react ön ucu
  • Azure Geliştirici CLI ile dağıtım için kod olarak altyapı

Bu öğreticinin sonunda, depolama kimlik bilgilerini tarayıcıya göstermeden güvenli dosya yüklemelerini gösteren Azure Container Apps'e dağıtılmış çalışan bir uygulamanız olacak.

Önkoşullar

Başlamadan önce şunların olduğundan emin olun:

Bahşiş

Bu öğreticide, tarayıcınızda önceden yapılandırılmış bir geliştirme ortamı sağlayan GitHub Codespaces kullanılır. Yerel kurulum gerekmez.

Architecture

Karşıya yükleme akışını gösteren Azure mimari diyagramı: Kullanıcı Web App Ön Uç'ta dosya seçer, ön uç API Uygulaması Arka Uç'tan SAS belirteci ister, arka uç Yönetilen Kimlikten kullanıcı temsilci anahtarı alır ve Depolama Blob Kapsayıcısı'ndan SAS belirteci oluşturur, ön uç SAS belirtecini kullanarak dosyayı doğrudan Depolama'ya yükler, arka uç yüklenen dosyaları listelemek için Depolama'ya sorgu yapar. Container Registry her iki uygulama için de kapsayıcı görüntüleri sağlar.

Ön uç, API'den bir SAS belirteci isteğinde bulunur ve ardından dosyaları doğrudan Azure Depolama'ya yükler. Yüklemeden sonra, API yüklenen tüm dosyaları görüntüleme amacıyla salt okunur SAS belirteçleri ile listeler.

'Dosyayı Azure Depolama Alanına Yükle' adlı ve Dosya Seç düğmesi ile 'upload' kapsayıcı adı görünen bir web uygulamasının ekran görüntüsü.

Temel kavramlar

Kullanıcı Yetki Aktarımı SAS belirteçleri

Uygulama güvenli, anahtarsız kimlik doğrulaması için Kullanıcı Temsilcisi SAS belirteçlerini kullanır. Bu belirteçler, Yönetilen Kimlik aracılığıyla Microsoft Entra Id kimlik bilgileriyle imzalanmış. API, belirli izinlere (okuma, yazma veya silme) sahip kısa süreli belirteçler (10-60 dakika) oluşturur ve tarayıcının kimlik bilgilerini göstermeden dosyaları doğrudan depolama alanına yüklemesine olanak tanır.

Azure Geliştirici CLI dağıtımı

Tüm altyapıyı azd up ile dağıtın. Bu, React ön ucu ve Fastify API arka ucu için Azure Container Apps sağlar, yönetilen kimlikleri yapılandırır ve RBAC izinleri atar. Altyapı, uygun olduğunda Azure Doğrulanmış Modüller ile Azure Well-Architected Framework ilkelerini izleyerek Bicep şablonlarını kullanır.

Geliştirme kapsayıcısı ortamı

Bu öğreticinin tam örnek kodu, GitHub Codespaces veya yerel Visual Studio Code ortamında bir geliştirme kapsayıcısı kullanır.

Uyarı

Bu öğreticiyi Geliştirme Kapsayıcıları uzantısıyla Visual Studio Code'da yerel olarak da çalıştırabilirsiniz. Örnek kodun tamamı geliştirme kapsayıcısı yapılandırmasını içerir.

Örneği GitHub Codespaces'ta açma

GitHub Codespaces , tüm bağımlılıkların önceden yüklenmiş olduğu tarayıcı tabanlı bir VS Code ortamı sağlar.

Önemli

Tüm GitHub hesapları codespaces'i her ay ücretsiz saatlerle kullanabilir. Daha fazla bilgi için bkz. GitHub Codespaces aylık olarak dahil edilen depolama ve çekirdek çalışma saatleri.

  1. Web tarayıcısında örnek depoyu açın ve Kod>Ana dalda kod alanı oluştur'u seçin.

    Dosyaya git, Dosya ekle ve yeşil Kod düğmesinin vurgulandığı GitHub deposu sayfasının ekran görüntüsü.

  2. Geliştirme kapsayıcısının başlatılmasını bekleyin. Bu başlatma işlemi birkaç dakika sürebilir. Bu öğreticideki kalan adımlar bu geliştirme kapsayıcısı bağlamında gerçekleşir.

Örneği dağıtma

  1. Azure'da oturum açın.

    azd auth login

  2. Kaynakları sağlayın ve örneği barındırma ortamına dağıtın.

    azd up

    İstendiğinde aşağıdaki bilgileri girin:

    Uyarı Gir
    Benzersiz bir ortam adı girin secure-upload
    Kullanılacak Azure Aboneliğini seçin Listeden aboneliğinizi seçin
    'location' altyapı parametresi için bir değer girin Kullanılabilir konumlardan seçim yapın

    Alternatif olarak, sağlanan kaynakları görmek ve ardından dağıtım çıkışını görmek isterseniz, istem olmadan dağıtmak için aşağıdaki komutu çalıştırabilirsiniz:

    azd provision

    Ardından uygulama kodunu dağıtmak için şu komutu çalıştırın:

    azd deploy

    API veya web uygulaması kodunu değiştirirseniz, aşağıdaki komutlardan biriyle yalnızca uygulama kodunu yeniden dağıtabilirsiniz:

    azd deploy app
azd deploy api

  3. Dağıtım tamamlandığında, terminalde görüntülenen dağıtılan web uygulamasının URL'sini not edin.

      (✓) Done: Deploying service app
  - Endpoint: https://app-gp2pofajnjhy6.calmtree-87e53015.eastus2.azurecontainerapps.io/

    Bu örnek bir URL'dir. URL'niz farklı olacaktır.

Örneği deneyin

  1. Dağıtılan web uygulamasını yeni bir tarayıcı sekmesinde açın ve karşıya yüklenecek PNG dosyasını seçin. Klasörde çeşitli PNG dosyaları bulunur ./docs/media .

    Azure Depolama'ya dosya yüklemek için Dosya Seç düğmesini ve kapsayıcı adını karşıya yüklemeyi gösteren web uygulamasının ekran görüntüsü.

  2. SAS belirteci al'ı ve ardından Dosyayı karşıya yükle'yi seçin.

  3. Yüklediğiniz dosyayı yükleme düğmesinin altındaki galeride görüntüleyin.

    daisies.jpg dosyası Azure Depolama'ya yüklendikten sonra, dosya adı, SAS URL'si, yükleme durumu ve görüntü küçük resmini gösteren web uygulamasının ekran görüntüsü.

Az önce ne oldu?

  • ** Zaman sınırlı, salt yazma izinli bir SAS belirteci kullanılarak dosyanız doğrudan tarayıcıdan Azure Depolama'ya yüklendi.
  • Galeri görüntüleri salt okunur SAS belirteçleri kullanılarak doğrudan Azure Depolama'dan yüklenir
  • Tarayıcınızda kimlik doğrulama sırları açığa çıkarılmadı

Kod nasıl çalışır?

Uygulamayı nasıl çalıştığını gördüğünüze göre kodun güvenli dosya yüklemelerini nasıl uyguladığını keşfedin. Uygulamanın iki ana bölümü vardır:

  1. API arka ucu - Azure ile kimlik doğrulaması yapar ve SAS belirteçleri oluşturur
  2. React ön ucu - SAS belirteçlerini kullanarak dosyaları doğrudan Azure Depolama'ya yükler

Aşağıdaki bölümlerde anahtar kodu uygulamalarına göz gezdirilir.

SAS belirteçleri ve liste dosyaları oluşturmak için API sunucusu

API sunucusu Azure Depolama'da kimlik doğrulaması yapar ve tarayıcının kullanması için zaman sınırlı SAS belirteçleri oluşturur.

Yönetilen Kimlik ile kimlik doğrulaması

Uygulama, Azure uygulamaları için en güvenli yaklaşım olan kimlik doğrulaması için Yönetilen Kimlik ile Kullanıcı Temsilcisi Anahtarları kullanır. Kimlik ChainedTokenCredential doğrulama yöntemlerini şu sırayla dener:

  1. Azure'da: ManagedIdentityCredential (Container Apps kimliği)
  2. Yerel geliştirme: AzureCliCredential (oturumunuz az login )
// From: packages/api/src/lib/azure-storage.ts
export function getCredential(): ChainedTokenCredential {
  if (!_credential) {
    const clientId = process.env.AZURE_CLIENT_ID;
    
    // Create credential chain with ManagedIdentity first
    const credentials = [
      new ManagedIdentityCredential(clientId ? { clientId } : undefined),
      new AzureCliCredential()
    ];
    
    _credential = new ChainedTokenCredential(...credentials);
  }
  return _credential;
}

Kimlik doğrulamasının ardından Azure Depolama ile etkileşim kurmak için bir BlobServiceClient oluşturun:

// From: packages/api/src/lib/azure-storage.ts
export function getBlobServiceClient(accountName: string): BlobServiceClient {
  const credential = getCredential();
  const url = `https://${accountName}.blob.core.windows.net`;
  
  return new BlobServiceClient(url, credential);
}

Kullanıcı Temsilci Anahtarları ile SAS belirteçleri oluşturma

SAS belirteçleri, depolama hesabı anahtarları yerine Microsoft Entra Id kimlik bilgilerini kullanarak belirtecin kimliğini doğrulayan bir Kullanıcı Temsilcisi Anahtarı gerektirir. Anahtar belirli bir zaman aralığı için geçerlidir:

const startsOn = new Date();
const expiresOn = new Date(startsOn.valueOf() + minutes * 60 * 1000);

const userDelegationKey = await blobServiceClient.getUserDelegationKey(
  startsOn,
  expiresOn
);

Dosya yüklemeleri için salt yazma SAS belirteçleri oluşturma

Dosya yüklemeleri için API, verileri okuyamaz veya silemez salt yazma belirteçleri oluşturur. Jetonlar 10 dakika sonunda geçerliliğini yitirir.

// From: packages/api/src/routes/sas.ts
const DEFAULT_SAS_TOKEN_PERMISSION = 'w';
const DEFAULT_SAS_TOKEN_EXPIRATION_MINUTES = 10;

const sasToken = generateBlobSASQueryParameters(
  {
    containerName: container,
    blobName: file,
    permissions: BlobSASPermissions.parse(permission),
    startsOn,
    expiresOn
  },
  userDelegationKey,
  accountName
).toString();

const sasUrl = `${blobClient.url}?${sasToken}`;

Kullanılabilir izin düzeyleri:

  • 'r' - Okuma (indirme/görüntüleme)
  • 'w' - Yazma (karşıya yükleme/üzerine yazma) - Karşıya yüklemeler için kullanılır
  • 'd' - Silmek
  • 'c' -Oluşturmak
  • 'a' - Ekle (ekleme blobları)

Dosyaları listelemek ve görüntülemek için salt okunur SAS belirteçleri oluşturma

Dosyaları listelemek ve görüntülemek için API, süresi 60 dakika sonra dolan salt okunur belirteçler oluşturur:

// From: packages/api/src/routes/list.ts
const LIST_SAS_TOKEN_PERMISSION = 'r';
const LIST_SAS_TOKEN_EXPIRATION_MINUTES = 60;

const sasToken = generateBlobSASQueryParameters(
  {
    containerName: container,
    blobName: blob.name,
    permissions: BlobSASPermissions.parse(LIST_SAS_TOKEN_PERMISSION),
    startsOn,
    expiresOn
  },
  userDelegationKey,
  accountName
).toString();

const sasUrl = `${blobClient.url}?${sasToken}`;

Web uygulaması istemcisi, API sunucusundan SAS belirteçlerini talep eder ve alır.

React ön uç API'den SAS belirteçleri isteğinde bulunur ve bunları kullanarak dosyaları doğrudan tarayıcıdan Azure Depolama'ya yükler.

Ön uç üç adımlı bir işlemi izler:

  1. Belirli bir dosya için API'den SAS belirteci isteme
  2. SAS belirteci URL'sini kullanarak doğrudan Azure Depolama'ya yükleme
  3. Karşıya yüklenen dosyaların listesini salt okunur SAS belirteçleriyle getir ve görüntüle

Bu mimari arka ucu basit tutar; yalnızca belirteçler oluşturur, hiçbir zaman dosya verilerini işlemez.

Blob Depolama SAS Belirteci'ni API sunucusundan isteyin

Kullanıcı bir dosya seçip "SAS Belirteci Al" seçeneğine tıkladığında ön uç API'den yalnızca yazma SAS belirteci istemektedir:

// From: packages/app/src/App.tsx
const handleFileSasToken = () => {
  const permission = 'w'; // write-only
  const timerange = 10;   // 10 minutes expiration

  if (!selectedFile) return;

  // Build API request URL
  const url = `${API_URL}/api/sas?file=${encodeURIComponent(
    selectedFile.name
  )}&permission=${permission}&container=${containerName}&timerange=${timerange}`;

  fetch(url, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json'
    }
  })
    .then((response) => {
      if (!response.ok) {
        throw new Error(`Error: ${response.status} ${response.statusText}`);
      }
      return response.json();
    })
    .then((data: SasResponse) => {
      const { url } = data;
      setSasTokenUrl(url); // Store the SAS URL for upload
    });
};

Ne olur:

  • Frontend gönderir: GET /api/sas?file=photo.jpg&permission=w&container=upload&timerange=10
  • API döndürür: { url: "https://storageaccount.blob.core.windows.net/upload/photo.jpg?sv=2024-05-04&..." }
  • Bu URL 10 dakika boyunca geçerlidir ve söz konusu bloba yalnızca yazma erişimi verir

SAS belirtecini kullanarak doğrudan Blob Depolama'ya yükleme

SAS belirteci URL'si alındıktan sonra ön uç dosyayı ArrayBuffer'a dönüştürür ve api'yi tamamen atlayarak dosyayı doğrudan Azure Depolama'ya yükler. Bu, sunucu yükünü azaltır ve performansı artırır.

Dosyayı ArrayBuffer'a dönüştürün.

// From: packages/app/src/lib/convert-file-to-arraybuffer.ts
export function convertFileToArrayBuffer(file: File): Promise<ArrayBuffer | null> {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();

    reader.onload = () => {
      const arrayBuffer = reader.result;
      resolve(arrayBuffer as ArrayBuffer);
    };

    reader.onerror = () => {
      reject(new Error('Error reading file.'));
    };

    reader.readAsArrayBuffer(file);
  });
}

Ardından, dosya verilerini BlockBlobClient'den @azure/storage-blob kullanarak SAS belirteci URL'si ile karşıya yükleyin.

// From: packages/app/src/App.tsx
const handleFileUpload = () => {
  console.log('SAS Token URL:', sasTokenUrl);

  // Convert file to ArrayBuffer
  convertFileToArrayBuffer(selectedFile as File)
    .then((fileArrayBuffer) => {
      if (fileArrayBuffer === null || fileArrayBuffer.byteLength < 1) {
        throw new Error('Failed to convert file to ArrayBuffer');
      }

      // Create Azure Storage client with SAS URL
      const blockBlobClient = new BlockBlobClient(sasTokenUrl);
      
      // Upload directly to Azure Storage
      return blockBlobClient.uploadData(fileArrayBuffer);
    })
    .then((uploadResponse) => {
      if (!uploadResponse) {
        throw new Error('Upload failed - no response from Azure Storage');
      }
      setUploadStatus('Successfully finished upload');
      
      // After upload, fetch the updated list of files
      const listUrl = `${API_URL}/api/list?container=${containerName}`;
      return fetch(listUrl);
    });
};

Önemli noktalar:

  • Dosya hiçbir zaman API sunucunuzdan geçmez
  • Karşıya yükleme, doğrudan tarayıcıdan Azure Depolama'ya gerçekleştirilir.
  • SAS belirteci isteğin kimliğini doğrular
  • Dosya işleme için sunucu bant genişliği veya işlem maliyeti yok

Dosyayı doğrudan Azure Depolama'dan getirme ve küçük resim görüntüsünü görüntüleme

Karşıya yükleme başarılı olduktan sonra ön uç, kapsayıcıdaki tüm dosyaların listesini getirir. Listedeki her dosya kendi salt okunur SAS belirteci ile birlikte gelir:

// From: packages/app/src/App.tsx
const listUrl = `${API_URL}/api/list?container=${containerName}`;

fetch(listUrl)
  .then((response) => {
    if (!response.ok) {
      throw new Error(`Error: ${response.status}`);
    }
    return response.json();
  })
  .then((data: ListResponse) => {
    setList(data.list); // Array of SAS URLs with read permission
  });

Yanıt örneği:

{
  "list": [
    "https://storageaccount.blob.core.windows.net/upload/photo1.jpg?sv=2024-05-04&se=2025-12-18T15:30:00Z&sr=b&sp=r&...",
    "https://storageaccount.blob.core.windows.net/upload/photo2.jpg?sv=2024-05-04&se=2025-12-18T15:30:00Z&sr=b&sp=r&..."
  ]
}

Ön uç, SAS URL'lerini doğrudan görüntü etiketlerinde kullanır. Tarayıcı, ekli salt okunur belirteçleri kullanarak Azure Depolama'dan görüntü getirir:

// From: packages/app/src/App.tsx
<Grid container spacing={2}>
  {list.map((item) => {
    const urlWithoutQuery = item.split('?')[0];
    const filename = urlWithoutQuery.split('/').pop() || '';
    const isImage = filename.endsWith('.jpg') || 
                    filename.endsWith('.png') || 
                    filename.endsWith('.jpeg');
    
    return (
      <Grid item xs={6} sm={4} md={3} key={item}>
        <Card>
          {isImage ? (
            <CardMedia component="img" image={item} alt={filename} />
          ) : (
            <Typography>{filename}</Typography>
          )}
        </Card>
      </Grid>
    );
  })}
</Grid>

Nasıl çalışır:

  • Listedeki her URL salt okunur SAS belirteci (sp=r) içerir
  • Tarayıcı doğrudan Azure Depolama'ya GET isteklerinde bulunur
  • Kimlik doğrulaması gerekmez - belirteç URL'dedir
  • Belirteçlerin süresi 60 dakika sonra doluyor (API'de yapılandırıldı)

Kaynakları temizleme

Bu eğitimi tamamladığınızda, devam eden maliyetlerden kaçınmak için tüm Azure kaynaklarını silin.

azd down

Sorun giderme

GitHub deposunda bu örnekle ilgili sorunları bildirin. Soruna aşağıdakileri ekleyin:

  • Makalenin URL'si
  • Makalenin sorunlu olan adımı veya bağlamı
  • Geliştirme ortamınız

Örnek kod

Sonraki Adımlar

Artık Azure Depolama'ya güvenli bir şekilde dosya yüklemeyi öğrendiğinize göre şu ilgili konuları inceleyin:

İlgili içerik

  • Last updated on