Azure Static Web Apps を構成する

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

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

注意

ルーティングを構成するのに以前使用されていた routes.json は非推奨となっています。 この記事の説明のとおりに staticwebapp.config.json を使用して、静的 Web アプリのルーティングやその他の設定を構成してください。

ファイルの場所

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

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

重要

staticwebapp.config.json がある場合、非推奨の routers.json ファイルは無視されます。

ルート

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

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

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

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

ルートの定義

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

規則のプロパティ 必須 既定値 解説
route はい 該当なし 呼び出し元によって要求されるルート パターン。
  • ルート パスの末尾には、ワイルドカードを使用できます。
    • たとえば、ルート admin/* は、admin パスの下にあるすべてのルートと一致します。
rewrite いいえ 該当なし 要求から返されるファイルまたはパスを定義します。
  • redirect 規則に対して相互に排他的です
  • 書き換え規則では、ブラウザーの場所は変更されません。
  • 値は、アプリのルートを基準にする必要があります
redirect いいえ 該当なし 要求のファイルまたはパスのリダイレクト先を定義します。
  • rewrite 規則に対して相互に排他的です。
  • リダイレクト規則では、ブラウザーの場所が変更されます。
  • 既定の応答コードは 302 (一時的なリダイレクト) ですが、301 (永続的なリダイレクト) でオーバーライドできます。
allowedRoles いいえ anonymous ルートにアクセスするために必要なロール名のリストを定義します。
  • 有効な文字は、a-zA-Z0-9_ です。
  • 組み込みロール anonymous は、認証されていないすべてのユーザーに適用されます。
  • 組み込みロール authenticated は、ログインしている任意のユーザーに適用されます。
  • ユーザーは、少なくとも 1 つのロールに属している必要があります。
  • ロールは、OR に基づいて照合されます。
    • ユーザーが一覧にあるいずれかのロールに属している場合は、アクセス権が付与されます。
  • 個々のユーザーは、招待によってロールに関連付けられます。
headers いいえ 該当なし 応答に追加される HTTP ヘッダーのセット。
  • ルート固有のヘッダーが応答内のグローバル ヘッダーと同じ場合、globalHeaders はルート固有のヘッダーによってオーバーライドされます。
  • ヘッダーを削除するには、値を空の文字列に設定します。
statusCode いいえ 200301、または 302 (リダイレクト用) 応答の HTTP 状態コード
methods いいえ すべてのメソッド ルートに一致する要求メソッドのリスト。 使用可能なメソッドには、GETHEADPOSTPUTDELETECONNECTOPTIONSTRACEPATCH があります。

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

目的 Properties
ルートと一致させる route, methods
ルートが一致した後に承認する allowedRoles
規則が一致して承認された後に処理する rewrite (要求を変更する)

redirectheadersstatusCode (応答を変更する)

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

ルートをセキュリティで保護するには、規則の 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
要求先 返されるもの 状態
/about/ index.html ファイル 200
/images/logo.png 画像ファイル 200
/images/icon.svg /index.html ファイル。svg ファイル拡張子が /images/*.{png,jpg,gif} フィルターに含まれていないため 200
/images/unknown.png "ファイルが見つかりませんでした" エラー 404
/css/unknown.css "ファイルが見つかりませんでした" エラー 404
/css/global.css スタイルシート ファイル 200
/images または /css フォルダー外にあるその他のファイル index.html ファイル 200

グローバル ヘッダー

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

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

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

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

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

応答のオーバーライド

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

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

状態コード 説明 考えられる原因
400 正しくない要求 無効な招待リンク
401 権限がありません 認証されていない状態での制限されたページへの要求
403 Forbidden
  • ユーザーはログインしているが、ページを表示するために必要なロールがない。
  • ユーザーはログインしているが、ランタイムが ID 要求からユーザーの詳細を取得できない。
  • カスタム ロールを使用してサイトにログインしているユーザーが多すぎるため、ランタイムでユーザーをログインさせることができない。
404 見つかりません ファイルが見つからない

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

{
  "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"
  }
}

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

要求先 結果
/profile 認証されたユーザーには、 /profile/index.html ファイルが提供されます。 認証されていないユーザーは /login にリダイレクトされます。
/admin/ administrator ロールの認証されたユーザーには、 /admin/index.html ファイルが提供されます。 administrator ロールに属していない認証されたユーザーには、403 エラーが返されます 1。 認証されていないユーザーは /login にリダイレクトされます。
/logo.png 最長有効期間が 182 日 (15,770,000 秒) を少し超えるカスタム キャッシュ規則を使用して画像を提供します。
/api/admin registeredusers ロールの認証されたユーザーからの GET 要求は、API に送信されます。 registeredusers ロールに属していない認証されたユーザー、および認証されていないユーザーには、401 エラーが返されます。

administrator ロールの認証されたユーザーからの POSTPUTPATCH、および DELETE 要求は、API に送信されます。 administrator ロールに属していない認証されたユーザー、および認証されていないユーザーには、401 エラーが返されます。
/customers/contoso administrator または customers_contoso ロールに属している認証されたユーザーには、 /customers/contoso/index.html ファイルが提供されます。 administrator または customers_contoso ロールに属していない認証されたユーザーには、403 エラーが返されます 1。 認証されていないユーザーは /login にリダイレクトされます。
/login 認証されていないユーザーは、GitHub で認証するように求められます。
/.auth/login/twitter Twitter での承認がルート規則によって無効になっているため、404 エラーが返されます。これにより、フォールバックされ、200 状態コードと共に /index.html が提供されます。
/logout ユーザーは、すべての認証プロバイダーからログアウトされます。
/calendar/2021/01 ブラウザーには、 /calendar.html ファイルが提供されます。
/specials ブラウザーは、永続的に /deals にリダイレクトされます。
/data.json MIME の種類 text/json で提供されるファイル。
/about、またはクライアント側のルーティング パターンに一致する任意のフォルダー /index.html ファイルは、200 状態コードと共に提供されます。
/Images/ フォルダー内に存在しないファイル 404 エラー。

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

制限

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

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

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

次のステップ