Die Datei routes.json, die bisher für die Konfiguration des Routings genutzt wurde, wurde als veraltet eingestuft. Verwenden Sie staticwebapp.config.json gemäß der Beschreibung in diesem Artikel, um das Routing und andere Einstellungen für Ihre statische Web-App zu konfigurieren.
Der für die Datei staticwebapp.config.json empfohlene Speicherort ist der Ordner, der in der Workflowdatei als app_location festgelegt wurde. Sie können die Datei jedoch in einem beliebigen Unterordner innerhalb des Ordners platzieren, der als app_location festgelegt ist. Wenn ein Buildschritt vorhanden ist, müssen Sie außerdem sicherstellen, dass der Buildschritt die Datei im Stammverzeichnis der output_location ausgibt.
Die veraltete Datei routes.json wird ignoriert, wenn die Datei staticwebapp.config.json vorhanden ist.
Routen
Sie können Regeln für eine oder mehrere Routen in Ihrer statischen Web-App definieren. Mit Routenregeln können Sie den Zugriff auf Benutzer in bestimmten Rollen einschränken oder Aktionen wie Umleiten oder Neuschreiben ausführen. Routen werden als Array von Routingregeln definiert. Beispiele der Nutzung finden Sie unter Beispielkonfigurationsdatei.
Regeln werden im routes-Array definiert, auch wenn sie nur über eine Route verfügen.
Regeln werden in der Reihenfolge ausgewertet, in der sie im routes-Array vorkommen.
Die Regelauswertung wird bei der ersten Übereinstimmung angehalten. Eine Übereinstimmung liegt vor, wenn die route-Eigenschaft und ein Wert im methods-Array (sofern angegeben) mit der Anforderung übereinstimmen. Jede Anforderung kann mit maximal einer Regel übereinstimmen.
Die Belange des Routings überschneiden sich erheblich mit den Konzepten der Authentifizierung (Identifizierung des Benutzers) und Autorisierung (Zuweisung von Berechtigungen zum Benutzer). Lesen Sie zusätzlich zu diesem Artikel den Leitfaden zur Authentifizierung und Autorisierung.
Definieren von Routen
Jede Regel besteht aus einem Routenmuster und einer oder mehreren optionalen Regeleigenschaften. Routenregeln werden im routes-Array definiert. Beispiele der Nutzung finden Sie unter Beispielkonfigurationsdatei.
Wichtig
Nur die Eigenschaften route und methods (sofern angegeben) werden verwendet, um zu bestimmen, ob eine Regel mit einer Anforderung übereinstimmt.
Regeleigenschaft
Erforderlich
Standardwert
Kommentieren
route
Ja
–
Das vom Aufrufer angeforderte Routenmuster.
Platzhalter am Ende der Routenpfade werden unterstützt.
Für die Route /admin* ergeben sich beispielsweise Übereinstimmungen mit allen Routen, die mit /admin beginnen.
methods
Nein
Alle Methoden
Definiert ein Array von Anforderungsmethoden, die einer Route entsprechen. Verfügbare Methoden: GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE und PATCH.
rewrite
Nein
–
Definiert die Datei oder den Pfad, die bzw. der von der Anforderung zurückgegeben wird.
Ist sich gegenseitig ausschließend mit einer redirect-Regel.
Neuschreibungsregeln ändern nicht den Speicherort des Browsers.
Werte müssen relativ zum Stamm der App sein.
redirect
Nein
–
Legt das Ziel der Datei- oder Pfadumleitung für eine Anforderung fest.
Ist sich gegenseitig ausschließend mit einer rewrite-Regel.
Umleitungsregeln ändern den Speicherort des Browsers.
Der Standardantwortcode ist 302 (temporäre Umleitung), aber Sie können ihn mit 301 überschreiben (permanente Umleitung).
Diese Regel entspricht Anforderungen für die Datei /profile/index.html. Da index.html die Standarddatei ist, entspricht die Regel auch Anforderungen für den Ordner (/profile oder /profile/).
Wichtig
Wenn Sie einen Ordnerpfad (/profile oder /profile/) in der route-Eigenschaft verwenden, entspricht er keinen Anforderungen für die Datei /profile/index.html. Verwenden Sie beim Schützen einer Route, die eine Datei bedient, immer den vollständigen Pfad der Datei, z. B. /profile/index.html.
Platzhaltermuster
Wildcardregeln entsprechen allen Anforderungen in einem Routenmuster und werden nur am Ende eines Pfads unterstützt. Beispiele der Nutzung finden Sie unter Beispielkonfigurationsdatei.
Falls Sie beispielsweise Routen für eine Kalenderanwendung implementieren möchten, können Sie alle URLs neu schreiben, die unter die Route calendar fallen, um eine einzelne Datei bereitzustellen.
Für die Datei calendar.html kann dann das clientseitige Routing verwendet werden, um eine andere Ansicht für URL-Varianten wie /calendar/january/1, /calendar/2020 und /calendar/overview bereitzustellen.
Hinweis
Das Routenmuster /calendar/* entspricht allen Anforderungen unter dem Pfad /calendar/. Es entspricht jedoch keinen Anforderungen für die Pfade /calendar oder /calendar.html. Verwenden Sie /calendar*, um alle Anforderungen abzugleichen, die mit /calendar beginnen.
Sie können Platzhalterübereinstimmungen nach Dateierweiterung filtern. Wenn Sie z. B. eine Regel hinzufügen möchten, die einen Abgleich nur auf HTML-Dateien in einem bestimmten Pfad vorsieht, könnten Sie die folgende Regel erstellen:
Gängige Anwendungsfälle für Platzhalterrouten sind z. B.:
Bereitstellen einer bestimmten Datei für ein ganzes Pfadmuster
Erzwingen von Authentifizierungs- und Autorisierungsregeln
Implementieren spezialisierter Cacheregeln
Schützen von Routen mit Rollen
Routen werden geschützt, indem dem Array allowedRoles einer Regel mindestens ein Rollenname hinzugefügt wird. Beispiele der Nutzung finden Sie unter Beispielkonfigurationsdatei.
Wichtig
Routingregeln können nur HTTP-Anforderungen an Routen schützen, die von Static Web Apps bedient werden. Viele Front-End-Frameworks verwenden clientseitiges Routing, das Routen im Browser ändert, ohne Anforderungen an Static Web Apps zu senden. Routingregeln schützen clientseitige Routen nicht. Clients sollten HTTP-APIs aufrufen, um vertrauliche Daten abzurufen. Stellen Sie sicher, dass APIs die Identität eines Benutzers überprüfen, bevor sie Daten zurückgeben.
Standardmäßig gehört jeder Benutzer zur integrierten Rolle anonymous, und alle angemeldeten Benutzer sind Mitglieder der Rolle authenticated. Optional werden Benutzer über Einladungen benutzerdefinierten Rollen zugeordnet.
Wenn Sie eine Route beispielsweise nur auf authentifizierte Benutzer beschränken möchten, fügen Sie die integrierte Rolle authenticated dem Array allowedRoles hinzu.
Sie können je nach Bedarf im Array allowedRoles neue Rollen erstellen. Um eine Route nur auf Administratoren zu beschränken, können Sie eine eigene Rolle mit dem Namen administrator im Array allowedRoles definieren.
Sie haben die volle Kontrolle über Rollennamen. Es gibt keine Liste, an die sich Ihre Rollen halten müssen.
Einzelne Benutzer werden Rollen mithilfe von Einladungen zugeordnet.
Wichtig
Geben Sie beim Sichern von Inhalten nach Möglichkeit genaue Dateien an. Wenn Sie viele Dateien sichern müssen, verwenden Sie Platzhalter hinter einem gemeinsam verwendeten Präfix. Beispiel: /profile* sichert alle möglichen Routen, die mit /profile beginnen, einschließlich /profile.
Einschränken des Zugriffs auf die gesamte Anwendung
Oft ist es sinnvoll, für jede Route in Ihrer Anwendung eine Authentifizierung anzufordern. Um Ihre Routen zu sperren, fügen Sie eine Regel hinzu, die allen Routen entspricht, und schließen Sie die integrierte authenticated-Rolle in das allowedRoles-Array ein.
Die folgende Beispielkonfiguration blockiert den anonymen Zugriff und leitet alle nicht authentifizierten Benutzer zur Anmeldeseite von Microsoft Entra um.
Standardmäßig sind alle vorkonfigurierten Identitätsanbieter aktiviert. Informationen zum Blockieren eines Authentifizierungsanbieters finden Sie unter Authentifizierung und Autorisierung.
Fallbackrouten
Single-Page-Anwendungen basieren häufig auf clientseitigem Routing. Diese clientseitigen Routingregeln aktualisieren den Fensterspeicherort des Browsers, ohne Anforderungen zurück an den Servern zu senden. Wenn Sie die Seite aktualisieren oder direkt zu URLs gehen, die mit clientseitigen Routingregeln generiert wurden, ist eine serverseitige Fallbackroute erforderlich, um die richtige HTML-Seite bereitzustellen. Die Fallbackseite wird häufig als index.html für Ihre clientseitige App festgelegt.
Hinweis
Routenregeln werden nicht auf Anforderungen angewendet, die navigationFallback auslösen.
Sie können eine Fallbackregel definieren, indem Sie einen Abschnitt vom Typ navigationFallback hinzufügen. Im folgenden Beispiel wird /index.html für alle statischen Dateianforderungen zurückgegeben, die keiner bereitgestellten Datei entsprechen.
Sie können einen Filter definieren, um zu steuern, für welche Anforderungen die Fallbackdatei zurückgegeben wird. Im folgenden Beispiel werden Anforderungen für bestimmte Routen im Ordner /images und alle Dateien im Ordner /css von der Rückgabe der Fallbackdatei ausgeschlossen.
Mit der folgenden Verzeichnisstruktur würde beispielsweise die oben genannte Fallbackregel für die Navigation zu den in der folgenden Tabelle aufgeführten Ergebnissen führen.
Die Datei /index.html, da die Dateierweiterung svg nicht im Filter /images/*.{png,jpg,gif} aufgeführt ist.
200
/images/unknown.png
Fehler „Datei nicht gefunden“.
404
/css/unknown.css
Fehler „Datei nicht gefunden“.
404
/css/global.css
Die Stylesheetdatei.
200
/about.html
Die HTML-Seite.
200
Alle anderen Pfade außerhalb der Ordner /images oder /css, die nicht mit dem Pfad zu einer bereitgestellten Datei übereinstimmen.
Die Datei /index.html.
200
Wichtig
Schließen Sie im Falle einer Migration von der veralteten Datei routes.json die Legacyfallbackroute ("route": "/*") nicht in die Routingregeln ein.
Globale Header
Der Abschnitt globalHeaders stellt eine Gruppe von HTTP-Headern bereit, die auf jede Antwort angewandt werden, es sei denn, sie werden durch eine Regel für Routenheader überschrieben. Andernfalls wird die Vereinigung sowohl der Header aus der Route als auch der globalen Header zurückgegeben.
Globale Header wirken sich nicht auf API-Antworten aus. Header in API-Antworten werden beibehalten und an den Client zurückgegeben.
Außerkraftsetzungen von Antworten
Der Abschnitt responseOverrides bietet die Möglichkeit, eine benutzerdefinierte Antwort zu definieren, wenn der Server sonst einen Fehlercode zurückgeben würde. Beispiele der Nutzung finden Sie unter Beispielkonfigurationsdatei.
Die folgenden HTTP-Codes sind zur Außerkraftsetzung verfügbar:
Der platform-Abschnitt steuert plattformspezifische Einstellungen, z. B. die Version der API-Sprachlaufzeit.
Auswählen der Version der API-Sprachlaufzeit
Legen Sie zum Konfigurieren der Version der API-Sprachlaufzeit die apiRuntime-Eigenschaft im platform-Abschnitt auf einen der folgenden unterstützten Werte fest.
Version der Sprachlaufzeit
Betriebssystem
Azure Functions-Version
Wert vom Typ apiRuntime
Supportende
.NET Core 3.1
Windows
3.x
dotnet:3.1
3\. Dezember 2022
.NET 6.0 (In-Process)
Windows
4.x
dotnet:6.0
-
.NET 6.0 (isoliert)
Windows
4.x
dotnet-isolated:6.0
-
.NET 7.0 (isoliert)
Windows
4.x
dotnet-isolated:7.0
-
.NET 8.0 (isoliert)
Windows
4.x
dotnet-isolated:8.0
-
Node.js 12.x
Linux
3.x
node:12
3\. Dezember 2022
Node.js 14.x
Linux
4.x
node:14
-
Node.js 16.x
Linux
4.x
node:16
-
Node.js 18.x
Linux
4.x
node:18
-
Node.js 20.x (Preview)
Linux
4.x
node:20
-
Python 3.8
Linux
4.x
python:3.8
-
Python 3.9
Linux
4.x
python:3.9
-
Python 3.10
Linux
4.x
python:3.10
-
.NET
Um die Runtimeversion in einer .NET-App zu ändern, ändern Sie den TargetFramework-Wert in der CSPROJ-Datei. Obwohl dies optional ist, sollten Sie, wenn Sie einen apiRuntime-Wert in der Datei staticwebapp.config.json festlegen, sicherstellen, dass der Wert mit dem übereinstimmt, den Sie in der CSPROJ-Datei definieren.
Im folgenden Beispiel wird veranschaulicht, wie das TargetFramework-Element für NET 8.0 als API-Sprachruntimeversion in der CSPROJ-Datei aktualisiert wird.
Die folgende Beispielkonfiguration veranschaulicht die Verwendung der apiRuntime-Eigenschaft, um Node.js 16 als Version der API-Sprachruntime in der staticwebapp.config.json-Datei auszuwählen.
Die folgende Beispielkonfiguration veranschaulicht die Verwendung der apiRuntime-Eigenschaft, um Python 3.8 als Version der API-Sprachruntime in der staticwebapp.config.json-Datei auszuwählen.
Der Abschnitt networking dient zum Steuern der Netzwerkkonfiguration Ihrer statischen Web-App. Wenn Sie den Zugriff auf Ihre App einschränken möchten, geben Sie in allowedIpRanges eine Liste zulässiger IP-Adressblöcke an. Weitere Informationen zur Anzahl zulässiger IP-Adressblöcke finden Sie unter Kontingente in Azure Static Web Apps.
Hinweis
Die Netzwerkkonfiguration ist nur im Standardplan für Azure Static Web Apps verfügbar.
Definieren Sie jeden IPv4-Adressblock in CIDR-Notation (Classless Inter-Domain Routing). Weitere Informationen zur CIDR-Notation finden Sie unter Classless Inter-Domain Routing. Jeder IPv4-Adressblock kann entweder einen öffentlichen oder einen privaten Adressraum darstellen. Wenn Sie nur Zugriff über eine einzelne IP-Adresse zulassen möchten, können Sie den CIDR-Block /32 verwenden.
Bei Angabe mindestens eines IP-Adressblocks wird Anforderungen, die von IP-Adressen stammen, die keinem Wert in allowedIpRanges entsprechen, der Zugriff verweigert.
Neben IP-Adressblöcken können Sie auch Diensttags im allowedIpRanges-Array angeben, um Datenverkehr auf bestimmte Azure-Dienste zu beschränken.
Weitere Informationen zum Einschränken von Routen auf authentifizierte Benutzer finden Sie unter Schützen von Routen mit Rollen.
Deaktivieren des Caches für authentifizierte Pfade
Wenn Sie die manuelle Integration in Azure Front Door eingerichtet haben, sollten Sie das Zwischenspeichern für Ihre geschützten Routen deaktivieren. Wenn Edge auf Unternehmensniveau aktiviert ist, ist die Zwischenspeicherung für Ihre gesicherten Routen bereits deaktiviert.
Um das Zwischenspeichern von Azure Front Door für geschützte Routen zu deaktivieren, fügen Sie der Routenheaderdefinition "Cache-Control": "no-store" hinzu.
Der Abschnitt forwardingGateway konfiguriert, wie der Zugriff auf eine statische Webanwendung von einem Weiterleitungsgateway wie einem Content Delivery Network (CDN) oder Azure Front Door erfolgt.
Hinweis
Die Konfiguration des Weiterleitungsgateways ist nur im Standardplan für Azure Static Web Apps verfügbar.
Zulässige weitergeleitete Hosts
Die allowedForwardedHosts Liste gibt an, welche Hostnamen im Header X-Forwarded-Host akzeptiert werden. Wenn eine übereinstimmende Domäne in der Liste enthalten ist, verwendet Static Web Apps den X-Forwarded-Host-Wert beim Erstellen von Umleitungs-URLs, z. B. nach einer erfolgreichen Anmeldung.
Damit Static Web Apps hinter einem Weiterleitungsgateway korrekt funktionieren, muss die Anforderung des Gateways den korrekten Hostnamen im X-Forwarded-Host-Header enthalten, und derselbe Hostname muss in allowedForwardedHosts aufgeführt sein.
Wenn der X-Forwarded-Host-Header nicht mit einem Wert in der Liste übereinstimmt, sind die Anforderungen trotzdem erfolgreich, aber der Header wird nicht in der Antwort verwendet.
Erforderliche Header
Erforderliche Header sind HTTP-Header, die bei jeder Anforderung an Ihre Website gesendet werden müssen. Eine Verwendung der erforderlichen Header besteht darin, den Zugriff auf eine Website zu verweigern, wenn nicht alle erforderlichen Header in jeder Anforderung vorhanden sind.
Die folgende Konfiguration zeigt beispielsweise, wie Sie einen eindeutigen Bezeichner für Azure Front Door hinzufügen können, der den Zugriff auf Ihre Website über eine bestimmte Azure Front Door-Instanz einschränkt. Ausführliche Informationen finden Sie im Tutorial zum Konfigurieren von Azure Front Door.
Schlüssel-Wert-Paare können beliebige Zeichenfolgen sein.
Bei Schlüsseln wird nicht zwischen Groß- und Kleinschreibung unterschieden.
Bei Werten werden Groß- und Kleinschreibung beachtet.
Nachstehender Schrägstrich
Ein nachstehender Schrägstrich ist das Zeichen / am Ende einer URL. Herkömmlicherweise verweist eine URL mit nachstehendem Schrägstrich auf ein Verzeichnis auf dem Webserver, eine URL ohne nachstehenden Schrägstrich hingegen auf eine Datei.
Suchmaschinen behandeln die beiden URLs separat, unabhängig davon, ob es sich um eine Datei oder ein Verzeichnis handelt. Wenn derselbe Inhalt unter beiden URLs gerendert wird, stellt Ihre Website doppelten Inhalt bereit, was sich negativ auf die Suchmaschinenoptimierung (Search Engine Optimization, SEO) auswirken kann. Bei expliziter Konfiguration wendet Static Web Apps Regeln zur URL-Normalisierung und -Umleitung an, die die Leistung Ihrer Website und Suchmaschinenoptimierung verbessern.
Die folgenden Normalisierungs- und Umleitungsregeln gelten für jede der verfügbaren Konfigurationen:
Always
Wenn Sie trailingSlash auf always festlegen, werden alle Anforderungen, die keinen nachstehenden Schrägstrich enthalten, an eine URL mit nachstehendem Schrägstrich umgeleitet. /contact wird beispielsweise an /contact/ umgeleitet.
"trailingSlash": "always"
Anforderungen:
Rückgabe
Mit dem Status
und Pfad...
/about
Die Datei /about/index.html
301
/about/
/about/
Die Datei /about/index.html
200
/about/
/about/index.html
Die Datei /about/index.html
301
/about/
/privacy.html
Die Datei /privacy.html
301
/privacy/
Nie
Wenn Sie trailingSlash auf never festlegen, werden alle Anforderungen, die auf einen nachstehenden Schrägstrich enden, an eine URL ohne nachstehenden Schrägstrich umgeleitet. /contact/ wird beispielsweise an /contact umgeleitet.
"trailingSlash": "never"
Anforderungen:
Rückgabe
Mit dem Status
und Pfad...
/about
Die Datei /about/index.html
200
/about
/about/
Die Datei /about/index.html
301
/about
/about/index.html
Die Datei /about/index.html
301
/about
/privacy.html
Die Datei /privacy.html
301
/privacy
Automatisch
Wenn Sie trailingSlash auf auto festlegen, werden alle Anforderungen für Ordner an eine URL mit einem nachstehenden Schrägstrich umgeleitet. Alle Anforderungen für Dateien werden an eine URL ohne nachstehenden Schrägstrich umgeleitet.
"trailingSlash": "auto"
Anforderungen:
Rückgabe
Mit dem Status
und Pfad...
/about
Die Datei /about/index.html
301
/about/
/about/
Die Datei /about/index.html
200
/about/
/about/index.html
Die Datei /about/index.html
301
/about/
/privacy.html
Die Datei /privacy.html
301
/privacy
Um eine optimale Websiteleistung zu erzielen, konfigurieren Sie mithilfe der Modi always, never oder auto eine Strategie mit nachstehendem Schrägstrich.
Wenn die Konfiguration trailingSlash nicht angegeben wird, wendet Static Web Apps standardmäßig die folgenden Regeln an:
Überprüfen Sie auf Grundlage der obigen Konfiguration die folgenden Szenarien.
Anforderungen:
Ergebnis
/profile
Für authentifizierte Benutzer wird die Datei /profile/index.html bereitgestellt. Nicht authentifizierte Benutzer werden von der Außerkraftsetzungsregel der 401-Antwort zu /login umgeleitet.
/admin, /admin/ oder /admin/index.html
Für authentifizierte Benutzer mit der Rolle administrator wird die Datei /admin/index.html bereitgestellt. Für authentifizierte Benutzer ohne die Rolle administrator wird ein 403-Fehler1 angezeigt. Nicht authentifizierte Benutzer werden zu /login umgeleitet.
/images/logo.png
Stellt das Image mit einer benutzerdefinierten Cacheregel bereit, deren maximales Alter bei etwas mehr als 182 Tagen (15.770.000 Sekunden) liegt.
/api/admin
GET-Anforderungen von authentifizierten Benutzern in der Rolle registeredusers werden an die API gesendet. Authentifizierte Benutzer ohne die Rolle registeredusers und nicht authentifizierte Benutzer erhalten den Fehler 401.
Die Anforderungen POST, PUT, PATCH und DELETE von authentifizierten Benutzern mit der Rolle administrator werden an die API gesendet. Für authentifizierte Benutzer ohne die Rolle administrator und nicht authentifizierte Benutzer wird der Fehler 401 angezeigt.
/customers/contoso
Für authentifizierte Benutzer mit der Rolle administrator oder customers_contoso wird die Datei /customers/contoso/index.html bereitgestellt. Für authentifizierte Benutzer ohne die Rolle administrator oder customers_contoso wird der Fehler4031 angezeigt. Nicht authentifizierte Benutzer werden zu /login umgeleitet.
/login
Nicht authentifizierte Benutzer werden aufgefordert, sich bei GitHub zu authentifizieren.
_/.auth/login/x
Da die Routenregel die X-Autorisierung deaktiviert, wird ein 404-Fehler zurückgegeben. Dieser Fehler führt dann ein Fallback mit der Bereitstellung von /index.html mit einem 200-Statuscode durch.
/logout
Benutzer werden von allen Authentifizierungsanbietern abgemeldet.
/calendar/2021/01
Für den Browser wird die Datei /calendar.html bereitgestellt.
/specials
Der Browser wird dauerhaft zu /deals umgeleitet.
/data.json
Die mit dem MIME-Typ text/json bereitgestellte Datei.
/about oder ein beliebiger Ordner, der mit clientseitigen Routingmustern übereinstimmt
Die Datei /index.html wird mit dem Statuscode 200 bereitgestellt.
Eine nicht vorhandene Datei im Ordner /images/.
Ein 404-Fehler.
1 Sie können eine benutzerdefinierte Fehlerseite bereitstellen, indem Sie eine Antwortüberschreibungsregel verwenden.
Beschränkungen
Die folgenden Einschränkungen gelten für die Datei staticwebapp.config.json:
Veröffentlichen Sie eine Angular-, React-, Svelte- oder Vue-JavaScript-Anwendung mit API und Authentifizierung mithilfe von Azure Static Web Apps und Azure Functions. Stellen Sie Ihren Code über GitHub mithilfe von Vorschau-URLs auf einer Stagingwebsite bereit.