Konfigurieren von Azure Static Web Apps

  • Artikel

Sie können die Konfiguration für Azure Static Web Apps in der Datei staticwebapp.config.json definieren, die die folgenden Einstellungen steuert:

Hinweis

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.

In diesem Dokument wird die Konfiguration von Azure Static Web Apps beschrieben – ein eigenständiges Produkt, das nicht zum Hosten von statischen Websites in Azure Storage gehört.

Datei-Lagerplatz

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.

Details finden Sie unter Beispielkonfigurationsdatei.

Wichtig

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).
statusCode Nein 301 oder 302 für Umleitungen Der HTTP-Statuscode der Antwort.
headers Nein – Gruppe von HTTP-Headern, die der Antwort hinzugefügt werden.
  • Routenspezifische Header überschreiben globalHeaders, wenn der routenspezifische Header dem globalen Header in der Antwort entspricht.
  • Um einen Header zu entfernen, legen Sie den Wert auf eine leere Zeichenfolge fest.
allowedRoles Nein anonymous Definiert ein Array von Rollennamen, die für den Zugriff auf eine Route erforderlich sind.
  • Gültige Zeichen sind a-z, A-Z, 0-9 und _.
  • Die integrierte Rolle anonymous gilt für alle Benutzer.
  • Die integrierte Rolle authenticated gilt für alle angemeldeten Benutzer.
  • Benutzern muss mindestens eine Rolle zugewiesen sein.
  • Rollen werden nach dem Muster OR (ODER) abgeglichen.
    • Wenn einem Benutzer eine beliebige aufgelistete Rolle zugewiesen ist, wird der Zugriff gewährt.
  • Einzelne Benutzer werden Rollen mithilfe von Einladungen zugeordnet.

Jede Eigenschaft hat in der Anforderungs-/Antwortpipeline einen bestimmten Zweck.

Zweck Eigenschaften
Routen abgleichen route, methods
Verarbeiten, nachdem für eine Route eine Übereinstimmung gefunden und sie autorisiert wurde rewrite (ändert Anforderung)

redirect, headers, statusCode (ändert Antwort)
Autorisieren, nachdem für eine Route eine Übereinstimmung gefunden wurde allowedRoles

Angeben von Routenmustern

Die route-Eigenschaft kann eine genaue Route oder ein Platzhaltermuster sein.

Genaue Route

Um eine genaue Route zu definieren, legen Sie den vollständigen Pfad der Datei in der route-Eigenschaft ab.

{
  "route": "/profile/index.html",
  "allowedRoles": ["authenticated"]
}

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.

{
  "route": "/calendar*",
  "rewrite": "/calendar.html"
}

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:

{
  "route": "/articles/*.html",
  "headers": {
    "Cache-Control": "public, max-age=604800, immutable"
  }
}

Um nach mehreren Dateierweiterungen zu filtern, schließen Sie die Optionen in geschweifte Klammern ein, wie in diesem Beispiel gezeigt:

{
  "route": "/images/thumbnails/*.{png,jpg,gif}",
  "headers": {
    "Cache-Control": "public, max-age=604800, immutable"
  }
}

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.

{
  "route": "/profile*",
  "allowedRoles": ["authenticated"]
}

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.

{
  "route": "/admin*",
  "allowedRoles": ["administrator"]
}
  • 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

Häufig sollten Sie für jede Route in Ihrer Anwendung eine Authentifizierung anfordern. 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.

{
  "routes": [
    {
      "route": "/*",
      "allowedRoles": ["authenticated"]
    }
  ],
  "responseOverrides": {
    "401": {
      "statusCode": 302,
      "redirect": "/.auth/login/aad"
    }
  }
}

Hinweis

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.

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.

{
  "navigationFallback": {
    "rewrite": "/index.html"
  }
}

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.

{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/images/*.{png,jpg,gif}", "/css/*"]
  }
}

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.

├── images
│   ├── logo.png
│   ├── headshot.jpg
│   └── screenshot.gif
│
├── css
│   └── global.css
│
└── index.html
Anforderungen: Rückgabe Mit dem Status
/about/ Die Datei /index.html. 200
/images/logo.png Die Bilddatei 200
/images/icon.svg 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
Alle anderen Dateien außerhalb der Ordner /images und /css 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.

Beispiele der Nutzung finden Sie unter Beispielkonfigurationsdatei.

Um einen Header zu entfernen, legen Sie den Wert auf eine leere Zeichenfolge ("") fest.

Zu den gängigen Anwendungsfällen für globale Header gehören u. a.:

  • Benutzerdefinierte Cacheregeln
  • Sicherheitsrichtlinien
  • Codierungseinstellungen
  • Siehe Konfigurieren der Ressourcenfreigabe zwischen verschiedenen Ursprüngen (CORS)

Im folgenden Beispiel wird eine benutzerdefinierte CORS-Konfiguration implementiert.

{
  "globalHeaders": {
    "Access-Control-Allow-Origin": "https://example.com",
    "Access-Control-Allow-Methods": "POST, GET, OPTIONS"
  }
}

Hinweis

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:

Statuscode Bedeutung Mögliche Ursache
400 Bad request (Ungültige Anforderung) Link zu ungültiger Einladung
401 Nicht autorisiert Anforderung eingeschränkter Seiten bei fehlender Authentifizierung
403 Verboten
  • Benutzer ist angemeldet, verfügt aber nicht über die erforderlichen Rollen, um die Seite anzuzeigen.
  • Benutzer ist angemeldet, aber die Laufzeit kann die Benutzerdetails nicht aus seinen Identitätsansprüchen abrufen.
  • Es sind zu viele Benutzer mit benutzerdefinierten Rollen bei der Website angemeldet, daher kann die Runtime den Benutzer nicht anmelden.
404 Nicht gefunden File not found

Die folgende Beispielkonfiguration zeigt, wie Sie einen Fehlercode überschreiben können.

{
  "responseOverrides": {
    "400": {
      "rewrite": "/invalid-invitation-error.html"
    },
    "401": {
      "statusCode": 302,
      "redirect": "/login"
    },
    "403": {
      "rewrite": "/custom-forbidden-page.html"
    },
    "404": {
      "rewrite": "/custom-404.html"
    }
  }
}

Plattform

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    ...
  </PropertyGroup>
...

Node.js

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.

{
  ...
  "platform": {
    "apiRuntime": "node:16"
  }
  ...
}

Python

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.

{
  ...
  "platform": {
    "apiRuntime": "python:3.8"
  }
  ...
}

Netzwerk

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.

{
  "networking": {
    "allowedIpRanges": [
      "10.0.0.0/24",
      "100.0.0.0/32",
      "192.168.100.0/22"
    ]
  }
}

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.

"networking": {
  "allowedIpRanges": ["AzureFrontDoor.Backend"]
}

Authentifizierung

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 mit 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.

Beispiel:

{
    "route": "/members",
    "allowedRoles": ["authenticated, members"],
    "headers": {
        "Cache-Control": "no-store"
    }
}

Weiterleitungsgateway

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.

"forwardingGateway": {
  "allowedForwardedHosts": [
    "example.org",
    "www.example.org",
    "staging.example.org"
  ]
}

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.

"forwardingGateway": {
  "requiredHeaders": {
    "X-Azure-FDID" : "692a448c-2b5d-4e4d-9fcc-2bc4a6e2335f"
  }
}
  • 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 die 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 eine Reihe von Regeln zur URL-Normalisierung und -Umleitung an, die die Leistung und SEO Ihrer Website 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/
/contact Die Datei /contact.html 301 /contact/
/contact/ Die Datei /contact.html 200 /contact/
/contact.html Die Datei /contact.html 301 /contact/

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
/contact Die Datei /contact.html 200 /contact
/contact/ Die Datei /contact.html 301 /contact
/contact.html Die Datei /contact.html 301 /contact

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/
/contact Die Datei /contact.html 200 /contact
/contact/ Die Datei /contact.html 301 /contact
/contact.html Die Datei /contact.html 301 /contact

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:

Anforderungen: Rückgabe Mit dem Status und Pfad...
/about Die Datei /about/index.html 200 /about
/about/ Die Datei /about/index.html 200 /about/
/about/index.html Die Datei /about/index.html 200 /about/index.html
/contact Die Datei /contact.html 200 /contact
/contact/ Die Datei /contact.html 301 /contact
/contact.html Die Datei /contact.html 200 /contact.html

Beispiel der Konfigurationsdatei

{
  "trailingSlash": "auto",
  "routes": [
    {
      "route": "/profile*",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/admin/index.html",
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/images/*",
      "headers": {
        "cache-control": "must-revalidate, max-age=15770000"
      }
    },
    {
      "route": "/api/*",
      "methods": ["GET"],
      "allowedRoles": ["registeredusers"]
    },
    {
      "route": "/api/*",
      "methods": ["PUT", "POST", "PATCH", "DELETE"],
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/api/*",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/customers/contoso*",
      "allowedRoles": ["administrator", "customers_contoso"]
    },
    {
      "route": "/login",
      "rewrite": "/.auth/login/github"
    },
    {
      "route": "/.auth/login/twitter",
      "statusCode": 404
    },
    {
      "route": "/logout",
      "redirect": "/.auth/logout"
    },
    {
      "route": "/calendar*",
      "rewrite": "/calendar.html"
    },
    {
      "route": "/specials",
      "redirect": "/deals",
      "statusCode": 301
    }
  ],
  "navigationFallback": {
    "rewrite": "index.html",
    "exclude": ["/images/*.{png,jpg,gif}", "/css/*"]
  },
  "responseOverrides": {
    "400": {
      "rewrite": "/invalid-invitation-error.html"
    },
    "401": {
      "redirect": "/login",
      "statusCode": 302
    },
    "403": {
      "rewrite": "/custom-forbidden-page.html"
    },
    "404": {
      "rewrite": "/404.html"
    }
  },
  "globalHeaders": {
    "content-security-policy": "default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'"
  },
  "mimeTypes": {
    ".json": "text/json"
  }
}

Ü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/twitter Da die Autorisierung bei Twitter durch die Routenregel deaktiviert ist, wird der Fehler 404 zurückgegeben, wodurch ein Fallback mit Bereitstellung von /index.html mit dem Statuscode 200 erfolgt.
/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:

  • Maximale Dateigröße: 20 KB
  • Maximal 50 verschiedene Rollen

Allgemeine Einschränkungen und Grenzwerte finden Sie im Artikel zu Kontingenten.

Nächste Schritte

Einrichten von Authentifizierung und Autorisierung