Azure Static Web Apps プレビューでのルートRoutes in Azure Static Web Apps Preview

Azure Static Web Apps でのルーティングでは、静的コンテンツと API の両方に対する、バックエンド ルーティング規則と承認動作が定義されています1Routing in Azure Static Web Apps defines back-end routing rules and authorization behavior for both static content and APIs1. 規則は、規則の配列として routes.json ファイルで定義されます。The rules are defined as an array of rules in the routes.json file.

  • routes.json ファイルは、アプリのビルド成果物フォルダーのルートに存在する必要があります。The routes.json file must exist at the root of app's build artifact folder.
  • 規則は、routes 配列に出現する順序で実行されます。Rules are executed in the order as they appear in the routes array.
  • 最初に一致した時点で、規則の評価は停止します。Rule evaluation stops at the first match. ルーティング規則は連結されません。Routing rules are not chained together.
  • ロールは routes.json ファイルで定義されており、ユーザーは招待によってロールに関連付けられます。Roles are defined in the routes.json file and users are associated to roles via invitations.
  • ロールの名前はお客様が完全に制御できます。You have full control over role names.

ルーティングのトピックは、認証と承認の概念とかなり重複します。The topic of routing significantly overlaps with authentication and authorization concepts. この記事と共に、認証と承認に関するガイドをお読みください。Make sure to read the authentication and authorization guide along with this article.

詳細については、ルート ファイルの例を参照してください。See the example route file for details.

場所Location

routes.json ファイルは、アプリのビルド成果物フォルダーのルートに存在する必要があります。The routes.json file must exist at the root of app's build artifact folder. Web アプリに、ビルドされたファイルを特定のフォルダーからビルド成果物フォルダーにコピーするビルド ステップが含まれている場合は、routes.json ファイルがその特定のフォルダーに存在している必要があります。If your web app includes a build step that copies built files from a specific folder to your build artifact folder, then the routes.json file needs to exist in that specific folder.

次の表では、いくつかのフロントエンド JavaScript フレームワークとライブラリについて、routes.json ファイルを配置する適切な場所を示します。The following table lists the appropriate location to put your routes.json file for a number of front-end JavaScript frameworks and libraries.

フレームワーク/ライブラリFramework / library 場所Location
AngularAngular assetsassets
ReactReact publicpublic
SvelteSvelte publicpublic
VueVue publicpublic

ルートの定義Defining routes

ルートは、routes プロパティのルート規則の配列として、routes.json ファイルで定義されています。Routes are defined in the routes.json file as an array of route rules on the routes property. 各規則は、ルート パターンと、1 つまたは複数のオプションの規則プロパティで構成されます。Each rule is composed of a route pattern, along with one or more of the optional rule properties. 使用例については、ルート ファイルの例を参照してください。See the example route file for usage examples.

規則のプロパティRule property 必須Required 既定値Default value 解説Comment
route はいYes 該当なしn/a 呼び出し元によって要求されるルート パターン。The route pattern requested by the caller.
  • ルート パスの末尾には、ワイルドカードを使用できます。Wildcards are supported at the end of route paths. たとえば、ルート admin/* は、admin パスの下にあるすべてのルートと一致します。For instance, the route admin/* matches any route under the admin path.
  • ルートの既定のファイルは、index.html です。A route's default file is index.html.
serve いいえNo 該当なしn/a 要求から返されるファイルまたはパスを定義します。Defines the file or path returned from the request. ファイルのパスと名前は、要求されたパスと異なっていてもかまいません。The file path and name can be different from the requested path. serve の値が定義されていない場合は、要求されたパスが使用されます。If a serve value is not defined, then the requested path is used. Querystring パラメーターはサポートされていません。serve の値では、実際のファイルが指定されている必要があります。Querystring parameters are not supported; serve values must point to actual files.
allowedRoles いいえNo anonymousanonymous ロール名の配列。An array of role names.
  • 有効な文字は、a-zA-Z0-9_ です。Valid characters include a-z, A-Z, 0-9, and _.
  • 組み込みのロール anonymous は、認証されていないすべてのユーザーに適用されます。The built-in role anonymous applies to all unauthenticated users.
  • 組み込みのロール authenticated は、ログインしているすべてのユーザーに適用されます。The built-in role authenticated applies to any logged-in user.
  • ユーザーは、少なくとも 1 つのロールに属している必要があります。Users must belong to at least one role.
  • ロールは、OR に基づいて照合されます。Roles are matched on an OR basis. ユーザーが一覧にあるいずれかのロールに属している場合は、アクセス権が付与されます。If a user is in any of the listed roles, then access is granted.
  • 個々のユーザーは、招待によってロールに関連付けられます。Individual users are associated to roles by through invitations.
statusCode いいえNo 200200 要求に対する HTTP 状態コードの応答。The HTTP status code response for the request.

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

ルートをセキュリティで保護するには、1 つまたは複数のロール名を規則の allowedRoles 配列に追加します。Routes are secured by adding one or more role names into a rule's allowedRoles array. 使用例については、ルート ファイルの例を参照してください。See the example route file for usage examples.

既定では、すべてのユーザーが組み込みの anonymous ロールに属し、ログインしているすべてのユーザーが authenticated ロールのメンバーになります。By default, every user belongs to the built-in anonymous role, and all logged-in users are members of the authenticated role. たとえば、認証されたユーザーのみにルートを制限するには、組み込みの authenticated ロールを allowedRoles 配列に追加します。For instance, to restrict a route to only authenticated users, add the built-in authenticated role to the allowedRoles array.

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

必要に応じて、allowedRoles 配列に新しいロールを作成できます。You can create new roles as needed in the allowedRoles array. ルートを管理者のみに制限するには、administrator ロールを allowedRoles 配列で定義します。To restrict a route to only administrators, you could define an administrator role in the allowedRoles array.

{
  "route": "/admin",
  "allowedRoles": ["administrator"]
}
  • ロールの名前は完全に制御できます。ロールが従う必要のあるマスター リストはありません。You have full control over role names; there's no master list to which your roles must adhere.
  • 個々のユーザーは、招待によってロールに関連付けられます。Individual users are associated to roles through invitations.

ワイルドカードWildcards

ワイルドカード規則は、指定されたルート パターンでのすべての要求と一致します。Wildcard rules match all requests under a given route pattern. 規則で serve の値を定義すると、指定したファイルまたはパスが応答として提供されます。If you define a serve value in your rule, the named file or path is served as the response.

たとえば、カレンダー アプリケーションに対するルートを実装するには、1 つのファイルを提供するように、calendar ルートの下にあるすべての URL をマップできます。For instance, to implement routes for a calendar application, you can map all URLs that fall under the calendar route to serve a single file.

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

その場合、calendar.html ファイルでは、クライアント側ルーティングを使用して、/calendar/january/1/calendar/2020/calendar/overview などの URL のバリエーションに対して異なるビューを提供できます。The calendar.html file can then use client-side routing to serve a different view for URL variations like /calendar/january/1, /calendar/2020, and /calendar/overview.

また、ワイルドカードを使用してルートをセキュリティで保護することもできます。You can also secure routes with wildcards. 次の例では、admin パスで要求されるすべてのファイルには、administrator ロールのメンバーである認証済みのユーザーが必要です。In the following example, any file requested under the admin path requires an authenticated user who is a member of the administrator role.

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

注意

提供されるファイルによって参照されているファイルへの要求は、認証チェックについてのみ評価されます。Requests for files referenced by a served file are only evaluated for authentication checks. たとえば、ワイルドカード パスの下にある CSS ファイルへの要求に対して提供されるのは CSS ファイルであり、serve ファイルとして定義されているものではありません。For instance, requests to a CSS file under a wildcard path serve the CSS file, and not what is defined as the serve file. ユーザーが必要な認証要件を満たしている限り、CSS ファイルが提供されます。The CSS file is served as long as the user meets the required authentication requirements.

フォールバック ルートFallback routes

フロントエンドの JavaScript フレームワークまたはライブラリは、多くの場合、Web アプリ ナビゲーションのクライアント側ルーティングに依存します。Front-end JavaScript frameworks or libraries often rely on client-side routing for web app navigation. これらのクライアント側ルーティング規則では、要求をサーバーに返さずに、ブラウザーのウィンドウの場所が更新されます。These client-side routing rules update the browser's window location without making requests back to the server. ページを更新する場合、またはクライアント側ルーティング規則によって生成された場所に直接移動する場合は、適切な HTML ページを提供するために、サーバー側フォールバック ルートが必要です。If you refresh the page, or navigate directly to locations generated by client-side routing rules, a server-side fallback route is required to serve the appropriate HTML page.

一般的なフォールバック ルートの例を次に示します。A common fallback route is shown in the following example:

{
  "routes": [
    {
      "route": "/*",
      "serve": "/index.html",
      "statusCode": 200
    }
  ]
}

フォールバック ルートは、それより前に定義されている規則によってキャッチされないすべての要求をキャッチするため、ルーティング規則の一覧の最後に追加する必要があります。The fallback route must be listed last in your routing rules, as it catches all requests not caught by previously defined rules.

リダイレクトRedirects

301 および 302 の HTTP 状態コードを使用して、あるルートから別のルートに要求をリダイレクトすることができます。You can use 301 and 302 HTTP status codes to redirect requests from one route to another.

たとえば、次の規則では、old-page.html から new-page.html への 301 リダイレクトが作成されます。For instance, the following rule creates a 301 redirect from old-page.html to new-page.html.

{
  "route": "/old-page.html",
  "serve": "/new-page.html",
  "statusCode": 301
}

リダイレクトは、個別のファイルが定義されていないパスでも機能します。Redirects also work with paths that don't define distinct files.

{
  "route": "/about-us",
  "serve": "/about",
  "statusCode": 301
}

カスタム エラー ページCustom error pages

ユーザーは、エラーが発生する可能性のあるさまざまな状況に遭遇する場合があります。Users may encounter a number of different situations that may result in an error. platformErrorOverrides 配列を使用して、これらのエラーに対するカスタム エクスペリエンスを提供できます。Using the platformErrorOverrides array, you can provide a custom experience in response to these errors. routes.json ファイルへの配列の配置については、ルート ファイルの例を参照してください。Refer to the example route file for placement of the array in the routes.json file.

注意

要求によってプラットフォーム オーバーライド レベルになると、ルート規則は再度実行されません。Once a request makes it to the platform overrides level, route rules are not run again.

次の表では、使用できるプラットフォーム エラー オーバーライドの一覧を示します。The following table lists the available platform error overrides:

エラーの種類Error type HTTP 状態コードHTTP status code 説明Description
NotFound 404404 ページがサーバーに見つかりません。A page is not found on the server.
Unauthenticated 401401 ユーザーは、認証プロバイダーを使用してログインしていません。The user is not logged in with an authentication provider.
Unauthorized_InsufficientUserInformation 401401 認証プロバイダーでのユーザーのアカウントは、必要なデータを公開するように構成されていません。The user's account on the authentication provider is not configured to expose required data. このエラーは、アプリが認証プロバイダーにユーザーのメール アドレスを要求したが、ユーザーがメール アドレスへのアクセスを制限している場合などに、発生することがあります。This error may happen in situations like when the app asks the authentication provider for the user's email address, but the user chose to restrict access to the email address.
Unauthorized_InvalidInvitationLink 401401 招待の有効期限が切れているか、ユーザーは別の受信者に対して生成された招待リンクを使用しました。An invitation has either expired, or the user followed an invitation link generated for another recipient.
Unauthorized_MissingRoles 401401 ユーザーは、必要なロールのメンバーではありません。The user is not a member of a required role.
Unauthorized_TooManyUsers 401401 サイトがユーザーの最大数に達したため、サーバーで追加が制限されています。The site has reached the maximum number of users, and the server is limiting further additions. このエラーがクライアントに対して公開されるのは、生成できる招待の数には制限がなく、一部のユーザーは招待に同意しない可能性があるためです。This error is exposed to the client because there's no limit to the number of invitations you can generate, and some users may never accept their invitation.
Unauthorized_Unknown 401401 ユーザーを認証しようとして、不明な問題が発生しました。There is an unknown problem while trying to authenticate the user. このエラーの原因の 1 つとして可能性があるのは、ユーザーがアプリケーションに同意していないため、ユーザーが認識されない場合です。One cause for this error may be that the user isn't recognized because they didn't grant consent to the application.

カスタム MIME の種類Custom mime types

routes 配列と同じレベルにリストされている mimeTypes オブジェクトを使用すると、MIME の種類をファイル拡張子と関連付けることができます。The mimeTypes object, listed at the same level as the routes array, allows you to associate MIME types with file extensions.

{
    "routes": [],
    "mimeTypes": {
        "custom": "text/html"
    }
}

上記の例では、拡張子が .custom のすべてのファイルは、text/html の MIME の種類で提供されます。In the example above, all files with the .custom extension are served with the text/html MIME type.

MIME の種類を使用するときは、次の考慮事項が重要です。The following considerations are important as you work with MIME types:

  • キーを null、空、または 50 文字より多くすることはできませんKeys cannot be null or empty, or more than 50 characters
  • 値を null、空、または 1000 文字より多くすることはできませんValues cannot be null or empty, or more than 1000 characters

既定のヘッダーDefault headers

routes 配列と同じレベルにリストされている defaultHeaders オブジェクトを使用すると、応答ヘッダーを追加、変更、または削除できます。The defaultHeaders object, listed at the same level as the routes array, allows you to add, modify, or remove response headers.

ヘッダーに対して値を指定すると、ヘッダーが追加または変更されます。Providing a value for a header either adds or modifies the header. 空の値を指定すると、クライアントに提供されるヘッダーが削除されます。Providing an empty value, removes the header from being served to the client.

{
    "routes": [],
    "defaultHeaders": {
      "content-security-policy": "default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'",
      "cache-control": "must-revalidate, max-age=6000",
      "x-dns-prefetch-control": ""
    }
}

上の例では、新しい content-security-policy ヘッダーが追加され、cache-control によってサーバーの既定値が変更され、x-dns-prefectch-control ヘッダーが削除されます。In the above example, a new content-security-policy header is added, the cache-control modifies the server default value, and the x-dns-prefectch-control header is removed.

ヘッダーを使用するときは、次の考慮事項が重要です。The following considerations are important as you work with headers:

  • キーを null または空にすることはできません。Keys cannot be null or empty.
  • 値を null または空にすると、ヘッダーが処理から削除されます。Null or empty values remove a header from processing.
  • キーまたは値が 8,000 文字を超えることはできません。Keys or values cannot exceed 8,000 characters.
  • 定義されたヘッダーは、すべての要求で提供されます。Defined headers are served with all requests.
  • routes.json で定義されているヘッダーは、静的コンテンツにのみ適用されます。Headers defined in routes.json only apply to static content. 関数のコードで API エンドポイントの応答ヘッダーをカスタマイズできます。You can customize response headers of a API endpoint in the function's code.

ルート ファイルの例Example route file

次の例では、routes.json ファイルで静的コンテンツと API に対するルート規則を作成する方法を示します。The following example shows how to build route rules for static content and APIs in a routes.json file. 一部のルートでは、認証関連のエンドポイントにアクセスする /.auth システム フォルダーを使用します。Some routes use the /.auth system folder that access authentication-related endpoints.

{
  "routes": [
    {
      "route": "/profile",
      "allowedRoles": ["authenticated"]
    },
    {
      "route": "/admin/*",
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/api/admin",
      "allowedRoles": ["administrator"]
    },
    {
      "route": "/customers/contoso",
      "allowedRoles": ["administrator", "customers_contoso"]
    },
    {
      "route": "/login",
      "serve": "/.auth/login/github"
    },
    {
      "route": "/.auth/login/twitter",
      "statusCode": "404"
    },
    {
      "route": "/logout",
      "serve": "/.auth/logout"
    },
    {
      "route": "/calendar/*",
      "serve": "/calendar.html"
    },
    {
      "route": "/specials",
      "serve": "/deals",
      "statusCode": 301
    }
  ],
  "platformErrorOverrides": [
    {
      "errorType": "NotFound",
      "serve": "/custom-404.html"
    },
    {
      "errorType": "Unauthenticated",
      "statusCode": "302",
      "serve": "/login"
    }
  ],
  "defaultHeaders": {
    "content-security-policy": "default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'"
  },
  "mimeTypes": {
      "custom": "text/html"
  }
}

次の例では、要求が規則と一致した場合の動作について説明します。The following examples describe what happens when a request matches a rule.

要求先Requests to... 結果Result in...
/profile/profile 認証されたユーザーには、 /profile/index.html ファイルが提供されます。Authenticated users are served the /profile/index.html file. 認証されていないユーザーは、 /login にリダイレクトされます。Unauthenticated users redirected to /login.
/admin/reports/admin/reports administrators ロールの認証されたユーザーには、 /admin/reports/index.html ファイルが提供されます。Authenticated users in the administrators role are served the /admin/reports/index.html file. administrators ロールではない認証されたユーザーには、401 エラー2が提供されます。Authenticated users not in the administrators role are served a 401 error2. 認証されていないユーザーは、 /login にリダイレクトされます。Unauthenticated users redirected to /login.
/api/admin/api/admin administrators ロールの認証されたユーザーからの要求は、API に送信されます。Requests from authenticated users in the administrators role are sent to the API. administrators ロールではない認証されたユーザーおよび認証されていないユーザーには、401 エラーが提供されます。Authenticated users not in the administrators role and unauthenticated users are served a 401 error.
/customers/contoso/customers/contoso administrators ロールまたは customers_contoso ロールに属している認証されたユーザーには、 /customers/contoso/index.html ファイル2が提供されます。Authenticated users who belong to either the administrators or customers_contoso roles are served the /customers/contoso/index.html file2. administrators ロールまたは customers_contoso ロールでない認証されたユーザーには、401 エラーが提供されます。Authenticated users not in the administrators or customers_contoso roles are served a 401 error. 認証されていないユーザーは、 /login にリダイレクトされます。Unauthenticated users redirected to /login.
/login/login 認証されていないユーザーは、GitHub で認証するように求められます。Unauthenticated users are challenged to authenticate with GitHub.
/.auth/login/twitter/.auth/login/twitter Twitter での承認は無効になっています。Authorization with Twitter is disabled. サーバーは 404 エラーで応答します。The server responds with a 404 error.
/logout/logout ユーザーは、すべての認証プロバイダーからログアウトされます。Users are logged out of any authentication provider.
/calendar/2020/01/calendar/2020/01 ブラウザーには、 /calendar.html ファイルが提供されます。The browser is served the /calendar.html file.
/specials/specials ブラウザーは /deals にリダイレクトされます。The browser is redirected to /deals.
/unknown-folder/unknown-folder /custom-404.html ファイルが提供されます。The /custom-404.html file is served.
.custom 拡張子のファイルFiles with the .custom extension MIME の種類 text/html で提供されますAre served with the text/html MIME type

すべての応答には、値が default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none' である content-security-policy ヘッダーが含まれます。All responses include the content-security-policy headers with a value of default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'.

1 API 関数のルート規則では、リダイレクトロールによるルートのセキュリティ保護のみがサポートされます。1 Route rules for API functions only support redirects and securing routes with roles.

2 platformErrorOverrides 配列で Unauthorized_MissingRoles 規則を定義することにより、カスタム エラー ページを提供できます。2 You can provide a custom error page by defining a Unauthorized_MissingRoles rule in the platformErrorOverrides array.

制限Restrictions

  • routes.json ファイルは、100 KB 以下にする必要がありますThe routes.json file cannot be more than 100 KB
  • routes.json ファイルでは、最大で 50 の異なるロールがサポートされていますThe routes.json file supports a maximum of 50 distinct roles

一般的な制限事項と限度については、クォータに関する記事を参照してください。See the Quotas article for general restrictions and limitations.

次のステップNext steps