Azure Static Web Apps を構成する

• 04/09/2021
• • c
  • o

Azure Static Web Apps の構成は、次の設定を制御する staticwebapp.config.json ファイルで定義されます。

• ルーティング
• 認証
• 承認
• フォールバック規則
• HTTP 応答のオーバーライド
• グローバル HTTP ヘッダーの定義
• カスタムの MIME の種類

ファイルの場所

staticwebapp.config.json の推奨される場所は、ワークフロー ファイルで app_location として設定されたフォルダー内です。 ただし、このファイルは、アプリケーションのソース コード フォルダー内の任意の場所に配置できます。

詳細については、「構成ファイルの例」を参照してください。

ルート

ルート規則を使用すると、アプリケーションから Web へのアクセスを許可する URL のパターンを定義できます。 ルートは、ルーティング規則の配列として定義します。 使用例については、「構成ファイルの例」を参照してください。

• 規則は、ルートが 1 つしかない場合でも routes 配列で定義します。
• 規則は、routes 配列に出現する順序で実行されます。
• 規則の評価は最初の一致で停止します。複数のルーティング規則が連結されることはありません。
• カスタム ロール名は完全に制御できます。
  • anonymous と authenticated を含む組み込みロール名がいくつかあります。

ルーティングの懸念事項は、認証 (ユーザーの識別) および承認 (ユーザーへの機能の割り当て) の概念とかなり重複しています。 この記事と共に、認証と承認に関するガイドをお読みください。

静的コンテンツの既定のファイルは、index.html ファイルです。

ルートの定義

各規則は、ルート パターンと、1 つまたは複数のオプションの規則プロパティで構成されます。 ルート規則は routes 配列で定義します。 使用例については、「構成ファイルの例」を参照してください。

各プロパティは、要求または応答パイプラインで特定の目的があります。

ロールによるルートのセキュリティ保護

ルートをセキュリティで保護するには、規則の allowedRoles 配列に 1 つ以上のロール名を追加します。ユーザーは、招待を介してカスタム ロールに関連付けられます。 使用例については、「構成ファイルの例」を参照してください。

既定では、すべてのユーザーが組み込みの anonymous ロールに属し、ログインしているすべてのユーザーが authenticated ロールのメンバーになります。

たとえば、認証されたユーザーのみにルートを制限するには、組み込みの authenticated ロールを allowedRoles 配列に追加します。

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

必要に応じて、allowedRoles 配列に新しいロールを作成できます。 ルートを管理者のみに制限するには、allowedRoles 配列に administrator という名前の独自のロールを定義できます。

{
  "route": "/admin",
  "allowedRoles": ["administrator"]
}

• ロールの名前は完全に制御できます。ロールが従う必要のあるリストはありません。
• 個々のユーザーは、招待によってロールに関連付けられます。

ワイルドカード

ワイルドカード規則は、ルート パターン内のすべての要求と一致し、パスの末尾でのみサポートされます。また、ファイル拡張子でフィルター処理できます。 使用例については、「構成ファイルの例」を参照してください。

たとえば、カレンダー アプリケーションに対するルートを実装するには、1 つのファイルを提供するように、calendar ルートに該当するすべての URL を書き換えることができます。

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

その場合、calendar.html ファイルでは、クライアント側ルーティングを使用して、/calendar/january/1、/calendar/2020、/calendar/overview などの URL のバリエーションに対して異なるビューを提供できます。

ワイルドカードの一致をファイル拡張子でフィルター処理できます。 たとえば、指定したパスの HTML ファイルのみに一致する規則を追加する場合は、次の規則を作成できます。

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

複数のファイル拡張子に基づいてフィルター処理するには、この例に示すように、オプションを中かっこで囲みます。

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

ワイルドカード ルートの一般的なユース ケースには、以下が含まれます。

• パス パターン全体に対して特定のファイルを提供する
• さまざまな HTTP メソッドをパス パターン全体にマップする
• 認証と承認の規則を適用する
• 特殊なキャッシュ規則を実装する

フォールバック ルート

シングル ページ アプリケーションは、多くの場合、クライアント側のルーティングに依存します。 これらのクライアント側ルーティング規則では、要求をサーバーに返さずに、ブラウザーのウィンドウの場所が更新されます。 ページを更新する場合、またはクライアント側ルーティング規則によって生成された URL に直接移動する場合は、適切な HTML ページ (通常はクライアント側アプリの index.html) を提供するために、サーバー側フォールバック ルートが必要です。

ファイル フィルターでパス ワイルドカードが使用されている次の例に示すように、フォールバック ルートを実装する規則を使用するようにアプリを構成できます。

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

次のファイル構造の例では、この規則を使用して次の結果を得ることができます。

├── images
│   ├── logo.png
│   ├── headshot.jpg
│   └── screenshot.gif
│
├── css
│   └── global.css
│
└── index.html

グローバル ヘッダー

globalHeaders セクションでは、ルート ヘッダー規則によってオーバーライドされない限り、各応答に適用される一連の HTTP ヘッダーが提供されます。それ以外の場合は、ルートからのヘッダーとグローバル ヘッダーの両方の和集合が返されます。

使用例については、「構成ファイルの例」を参照してください。

ヘッダーを削除するには、値を空の文字列 ("") に設定します。

グローバル ヘッダーの一般的なユース ケースには、以下が含まれます。

• カスタム キャッシュ ルール
• セキュリティ ポリシーの適用
• エンコードの設定

応答のオーバーライド

responseOverrides セクションでは、サーバーからエラー コードが返される場合のカスタム応答を定義できます。 使用例については、「構成ファイルの例」を参照してください。

次の HTTP コードをオーバーライドできます。

次の構成例は、エラー コードをオーバーライドする方法を示しています。

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

構成ファイルの例

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

上記の構成に基づいて、次のシナリオを確認します。

¹ 応答のオーバーライド規則を使用することにより、カスタム エラー ページを提供できます。

制限

staticwebapps.config.json ファイルには次の制限があります。

• 最大ファイル サイズは 100 KB
• 最大 50 種類のロール

一般的な制限事項と限度については、クォータに関する記事を参照してください。

次のステップ