Lernprogramm: Hochladen eines Bilds in ein Azure Storage-Blob mit TypeScript

In diesem Lernprogramm erfahren Sie, wie Sie Dateien aus einem Browser direkt in Azure Blob Storage hochladen, ohne Anmeldeinformationen verfügbar zu machen. Sie verwenden TypeScript, um das Valet-Schlüsselmuster mit SAS-Token (Shared Access Signature) und verwalteter Identität für sichere, schlüssellose Authentifizierung zu implementieren.

Die Beispielanwendung umfasst:

Eine Fastify-API, die zeitlich begrenzte SAS-Token generiert
Ein React-Frontend, das Dateien direkt in Azure Storage hochlädt
Infrastruktur als Code für die Bereitstellung mit azure Developer CLI

Am Ende dieses Lernprogramms haben Sie eine funktionierende Anwendung für Azure-Container-Apps bereitgestellt, die sichere Dateiuploads veranschaulicht, ohne Speicheranmeldeinformationen für den Browser verfügbar zu machen.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

Ein Azure-Abonnement – kostenlos erstellen
Ein GitHub-Konto zur Verwendung von GitHub Codespaces (einschließlich kostenloser monatlicher Stunden)

Tipp

In diesem Lernprogramm werden GitHub Codespaces verwendet, die eine vorkonfigurierte Entwicklungsumgebung in Ihrem Browser bereitstellt. Es ist kein lokales Setup erforderlich.

Architektur

Azure-Architekturdiagramm, das den Uploadablauf zeigt: Der Benutzer wählt die Datei im Web-App-Frontend aus, das Frontend fordert ein SAS-Token vom API-App-Backend an, das Backend ruft den Benutzerdelegierungsschlüssel von der verwalteten Identität ab und generiert ein SAS-Token aus dem Storage-Blob-Container. Das Frontend lädt die Datei direkt mit dem SAS-Token in den Speicher hoch, und das Backend fragt den Speicher ab, um hochgeladene Dateien aufzulisten. Die Containerregistrierung stellt Containerimages für beide Apps bereit.

Das Frontend fordert ein SAS-Token aus der API an und lädt dann Dateien direkt in Azure Storage hoch. Nach dem Hochladen listet die API alle hochgeladenen Dateien mit schreibgeschützten SAS-Token zur Anzeige auf.

Screenshot einer Web-App mit dem Titel

Wichtige Begriffe

SAS-Token der Benutzerdelegierung

Die Anwendung verwendet SAS-Token der Benutzerdelegierung für sichere, schlüssellose Authentifizierung. Diese Token werden mit Microsoft Entra ID-Anmeldeinformationen über verwaltete Identität signiert. Die API generiert kurzlebige Token (10-60 Minuten) mit bestimmten Berechtigungen (Lesen, Schreiben oder Löschen), sodass der Browser Dateien direkt in den Speicher hochladen kann, ohne Anmeldeinformationen verfügbar zu machen.

Azure Developer CLI-Bereitstellung

Die vollständige Infrastruktur mit azd up bereitstellen. Dadurch werden Azure Container-Apps für das React-Frontend und das Fastify-API-Back-End bereitgestellt, verwaltete Identitäten konfiguriert und RBAC-Berechtigungen zugewiesen. Die Infrastruktur verwendet Bicep-Vorlagen nach den Prinzipien des Azure Well-Architected Frameworks mit Azure Verified Modules, wo zutreffend.

Entwicklungscontainerumgebung

Im vollständigen Beispielcode dieses Tutorials wird ein Entwicklungscontainer in GitHub Codespaces oder in Visual Studio Code genutzt.

Hinweis

Sie können dieses Lernprogramm auch lokal in Visual Studio Code mit der Erweiterung Dev Containers ausführen. Der vollständige Beispielcode enthält die Konfiguration des Entwicklungscontainers.

Öffnen des Beispiels in GitHub Codespaces

GitHub Codespaces bietet eine browserbasierte VS Code-Umgebung mit vorinstallierten Abhängigkeiten.

Wichtig

Alle GitHub-Konten können Codespaces mit kostenlosen Stunden jeden Monat verwenden. Weitere Informationen finden Sie im Artikel zu monatlich enthaltener Speicherkapazität und Kernstunden in GitHub Codespaces.

Öffnen Sie in einem Webbrowser das Beispiel-Repository und wählen Sie Code>Codespace auf Haupt erstellen aus.
Warten Sie, bis der Entwicklungscontainer gestartet wird. Dieser Startvorgang kann einige Minuten dauern. Die verbleibenden Schritte in diesem Lernprogramm finden im Kontext dieses Entwicklungscontainers statt.

Bereitstellen des Beispiels

Melden Sie sich bei Azure an.
```
azd auth login
```

Stellen Sie Ressourcen bereit, und stellen Sie das Beispiel in der Hostingumgebung bereit.

azd up

Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Informationen ein:

Aufforderung	EINGABETASTE
Geben Sie einen eindeutigen Umgebungsnamen ein.	`secure-upload`
Wählen Sie ein Azure-Abonnement aus, das Sie verwenden möchten.	Wählen Sie Ihr Abonnement aus der Liste aus.
Geben Sie einen Wert für den Infrastrukturparameter "location" ein.	Wählen Sie aus den verfügbaren Speicherorten aus

Wenn Sie die bereitgestellten Ressourcen sehen möchten, können Sie alternativ den folgenden Befehl ausführen, um ohne Eingabeaufforderungen bereitzustellen:

azd provision

Führen Sie dann diesen Befehl aus, um den Anwendungscode bereitzustellen:

azd deploy

Wenn Sie den API- oder Web-App-Code ändern, können Sie nur den Anwendungscode mit einem der folgenden Befehle erneut bereitstellen:

azd deploy app
azd deploy api

Wenn die Bereitstellung abgeschlossen ist, notieren Sie sich die URL der bereitgestellten Web-App, die im Terminal angezeigt wird.
```
  (✓) Done: Deploying service app
  - Endpoint: https://app-gp2pofajnjhy6.calmtree-87e53015.eastus2.azurecontainerapps.io/
```
Dies ist eine Beispiel-URL. Ihre URL unterscheidet sich.

Testen des Beispiels

Öffnen Sie die bereitgestellte Web-App auf einer neuen Browserregisterkarte, und wählen Sie eine PNG-Datei aus, die hochgeladen werden soll. Mehrere PNG-Dateien sind im ./docs/media Ordner verfügbar.
Wählen Sie "SAS-Token abrufen" und dann " Datei hochladen" aus.
Sehen Sie Ihre hochgeladene Datei in der Galerie unterhalb der Schaltfläche "Hochladen" an.

Was ist gerade passiert?

Ihre Datei, die direkt vom Browser in Azure Storage hochgeladen wurde, verwendet ein zeitlich begrenztes, schreibgeschütztes SAS-Token.
Die Galeriebilder werden direkt aus Azure Storage mit schreibgeschützten SAS-Token geladen.
In Ihrem Browser wurden keine Authentifizierungsgeheimnisse verfügbar gemacht.

Funktionsweise des Codes

Nachdem Sie die Anwendung nun in Aktion gesehen haben, erfahren Sie, wie der Code sichere Dateiuploads implementiert. Die Anwendung hat zwei Hauptteile:

API-Back-End – Authentifiziert sich mit Azure und generiert SAS-Token
React-Frontend – Lädt Dateien direkt mit SAS-Token in Azure Storage hoch.

In den folgenden Abschnitten werden die wichtigsten Codeimplementierungen erläutert.

API-Server zum Generieren von SAS-Token und Listendateien

Der API-Server authentifiziert sich bei Azure Storage und generiert zeitlich begrenzte SAS-Token für den zu verwendenden Browser.

Authentifizierung mit verwalteter Identität

Die Anwendung verwendet Benutzerdelegierungsschlüssel mit verwalteter Identität für die Authentifizierung. Dies ist der sicherste Ansatz für Azure-Anwendungen. Die ChainedTokenCredential Authentifizierungsmethoden werden in dieser Reihenfolge versucht:

In Azure: ManagedIdentityCredential (Container-Apps-Identität)
Lokale Entwicklung: AzureCliCredential (Ihre az login Sitzung)

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

Erstellen Sie nach der Authentifizierung eine BlobServiceClient für die Interaktion mit Azure Storage:

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

Generieren von SAS-Token mit Benutzerdelegierungsschlüsseln

SAS-Token erfordern einen Benutzerdelegierungsschlüssel, der das Token mithilfe von Microsoft Entra-ID-Anmeldeinformationen anstelle von Speicherkontoschlüsseln authentifiziert. Der Schlüssel ist für einen bestimmten Zeitraum gültig:

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

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

Generieren von schreibgeschützten SAS-Tokens für Dateiuploads

Bei Dateiuploads generiert die API schreibgeschützte Token, die keine Daten lesen oder löschen können. Die Token laufen nach 10 Minuten ab:

// 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}`;

Verfügbare Berechtigungsstufen:

'r' - Lesen (Download/Ansicht)
'w' - Schreiben (Hochladen/Überschreiben) – Wird für Uploads verwendet
'd' -Löschen
'c' - Erstellen
'a' - Hinzufügen (Anfügen von Blobs)

Generieren von schreibgeschützten SAS-Token zum Auflisten und Anzeigen von Dateien

Zum Auflisten und Anzeigen von Dateien generiert die API schreibgeschützte Token, die nach 60 Minuten ablaufen:

// 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 App-Clientanforderung und Empfangen von SAS-Token vom API-Server

Das React-Frontend fordert SAS-Token aus der API an und verwendet sie, um Dateien direkt aus dem Browser in Azure Storage hochzuladen.

Das Frontend folgt einem dreistufigen Prozess:

Anfordern eines SAS-Tokens aus der API für eine bestimmte Datei
Direktes Hochladen in Azure Storage mithilfe der SAS-Token-URL
Abrufen und Anzeigen der Liste der hochgeladenen Dateien mit schreibgeschützten SAS-Token

Diese Architektur behält das Back-End-Leichtgewicht bei – es generiert nur Token, verarbeitet niemals Dateidaten.

Ein BLOB Storage SAS-Token vom API-Server anfordern

Wenn ein Benutzer eine Datei auswählt und auf "SAS-Token abrufen" klickt, fordert das Frontend ein schreibgeschütztes SAS-Token aus der API an:

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

Was ist los:

Frontend sendet: GET /api/sas?file=photo.jpg&permission=w&container=upload&timerange=10
API-Rückgaben: { url: "https://storageaccount.blob.core.windows.net/upload/photo.jpg?sv=2024-05-04&..." }
Diese URL ist 10 Minuten gültig und gewährt schreibgeschützten Zugriff auf dieses bestimmte Blob.

Direktes Hochladen in Blob Storage mithilfe des SAS-Tokens

Sobald die SAS-Token-URL empfangen wurde, konvertiert das Frontend die Datei in einen ArrayBuffer und lädt die Datei direkt in Azure Storage hoch . Die API wird vollständig umgangen. Dadurch wird die Serverlast reduziert und die Leistung verbessert.

Konvertieren Sie die Datei in einen ArrayBuffer.

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

Verwenden Sie dann den BlockBlobClient von @azure/storage-blob, um die Dateidaten mithilfe der SAS-Token-URL hochzuladen.

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

Wichtige Punkte:

Die Datei wird niemals über Ihren API-Server übergeben.
Upload wechselt direkt vom Browser zu Azure Storage
Das SAS-Token authentifiziert die Anforderung.
Keine Serverbandbreite oder Verarbeitungskosten für die Dateiverarbeitung

Abrufen der Datei direkt aus Azure Storage und Anzeigen des Miniaturbilds

Nach einem erfolgreichen Upload ruft das Frontend eine Liste aller Dateien im Container ab. Jede Datei in der Liste enthält ein eigenes schreibgeschütztes SAS-Token:

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

Antwortbeispiel:

{
  "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&..."
  ]
}

Das Frontend verwendet die SAS-URLs direkt in Bildtags. Der Browser ruft Bilder aus Azure Storage mithilfe der eingebetteten schreibgeschützten Token ab:

// 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>

Funktionsweise:

Jede URL in der Liste enthält ein schreibgeschütztes SAS-Token (sp=r)
Der Browser sendet GET-Anforderungen direkt an Azure Storage.
Keine Authentifizierung erforderlich – das Token befindet sich in der URL.
Token laufen nach 60 Minuten ab (in der API konfiguriert)

Bereinigen von Ressourcen

Wenn Sie mit diesem Lernprogramm fertig sind, entfernen Sie alle Azure-Ressourcen, um laufende Gebühren zu vermeiden:

azd down

Fehlerbehebung

Melden Sie Probleme mit diesem Beispiel im GitHub-Repository. Fügen Sie Folgendes dem Problem hinzu:

Die URL des Artikels
Der Schritt oder kontext im Artikel, der problematisch war
Ihre Entwicklungsumgebung

Beispielcode

GitHub-Repository: Azure-Samples/azure-typescript-upload-file-storage-blob

Nächste Schritte

Nachdem Sie nun gelernt haben, wie Sie Dateien sicher in Azure Storage hochladen können, erkunden Sie die folgenden verwandten Themen:

Dokumentation zu Azure Blob Storage – Informationen zu Speicherebenen, Lebenszyklusverwaltung und erweiterten Features
@azure/storage-blob npm-Paket – Entdecken Sie die vollständige SDK-Referenz und zusätzliche Funktionen
Valet Key-Muster – Verstehen des Architekturmusters hinter dieser Lösung
Bewährte Methoden für verwaltete Identität – Sichern Ihrer Azure-Anwendungen

Feedback

War diese Seite hilfreich?

Last updated on 2025-12-20