翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

Amplify ホスティングのデプロイ仕様を使用したビルド出力の設定

Amplify ホスティングのデプロイ仕様は、Amplify ホスティングへのデプロイを容易にするディレクトリ構造を定義するファイルシステムベースの仕様です。フレームワークは、ビルドコマンドの出力としてこの想定されるディレクトリ構造を生成できます。これにより、フレームワークは Amplify ホスティングのサービスプリミティブを利用できるようになります。Amplify ホスティングは、デプロイバンドルの構造を理解し、それに応じてデプロイします。

デプロイ仕様の使用方法を説明する動画デモについては、Amazon Web Services チャンネルの「 を使用してウェブサイトをホストする方法 AWS Amplify」を参照してください。 YouTube

Amplify がデプロイバンドルについて想定するフォルダ構造の例を次に示します。大まかに言うと、static という名前のフォルダ、compute という名前のフォルダ、deploy-manifest.json という名前のデプロイマニフェストファイルがあります。

.amplify-hosting/
├── compute/
│   └── default/
│       ├── chunks/
│       │   └── app/
│       │       ├── _nuxt/
│       │       │   ├── index-xxx.mjs
│       │       │   └── index-styles.xxx.js
│       │       └── server.mjs
│       ├── node_modules/
│       └── server.js
├── static/
│   ├── css/
│   │   └── nuxt-google-fonts.css
│   ├── fonts/
│   │   ├── font.woff2
│   ├── _nuxt/
│   │   ├── builds/
│   │   │   └── latest.json
│   │   └── entry.xxx.js
│   ├── favicon.ico
│   └── robots.txt
└── deploy-manifest.json

Amplify SSRプリミティブサポート

Amplify ホスティングのデプロイ仕様は、次のプリミティブに機密にマッピングされるコントラクトを定義します。

- .amplify-hosting/static directory

アプリケーションから提供されることを意図したパブリックにアクセス可能なすべての静的ファイルを URL .amplify-hosting/static ディレクトリに配置する必要があります。このディレクトリ内のファイルは、静的アセットのプリミティブを介して提供されます。

静的ファイルは、コンテンツ、ファイル名、または拡張子を変更URLすることなく、アプリケーションのルート (/) でアクセスできます。さらに、サブディレクトリは URL構造に保持され、ファイル名の前に表示されます。一例として、.amplify-hosting/static/favicon.ico は https://myAppId.amplify-hostingapp.com/favicon.ico から提供され、.amplify-hosting/static/_nuxt/main.js は https://myAppId.amplify-hostingapp.com/_nuxt/main.js から提供されます

フレームワークがアプリケーションのベースパスを変更する機能をサポートしている場合は、.amplify-hosting/static ディレクトリ内の静的アセットへのベースパスを先頭に付加する必要があります。例えば、ベースパスが /folder1/folder2 である場合、main.css という静的アセットのビルド出力は .amplify-hosting/static/folder1/folder2/main.css になります。

- .amplify-hosting/compute directory

単一のコンピューティングリソースは、.amplify-hosting/compute ディレクトリ内に含まれる defaultという名前の単一のサブディレクトリによって表されます。パスは .amplify-hosting/compute/default です。このコンピューティングリソースは、Amplify ホスティングのコンピューティングプリミティブにマッピングされます。

default サブディレクトリの内容は、次のルールに準拠する必要があります。

Amplify ホスティングは、default サブディレクトリ内のすべてのファイルをバンドルし、プロビジョニングされたコンピューティングリソースにデプロイします。各コンピューティングリソースには、512 MB のエフェメラルストレージが割り当てられます。このストレージは実行インスタンス間では共有されませんが、同じ実行インスタンス内での後続の呼び出しの間では共有されます。実行インスタンスの実行時間は最大 15 分に制限されており、実行インスタンス内の唯一の書き込み可能なパスは /tmp ディレクトリです。各コンピューティングリソースバンドルの圧縮サイズは 220 MB を超えることはできません。例えば、.amplify/compute/default サブディレクトリは圧縮された際に 220 MB を超えることはできません。

- .amplify-hosting/deploy-manifest.json file

デプロイの設定の詳細とメタデータを保存するには deploy-manifest.json ファイルを使用します。deploy-manifest.json ファイルには少なくとも、version 属性、キャッチオールルートが指定された routes 属性、およびフレームワークメタデータが指定された framework 属性が含まれている必要があります。

次のオブジェクト定義は、デプロイマニフェストの設定を示しています。

type DeployManifest = {
  version: 1;
  routes: Route[];
  computeResources?: ComputeResource[];
  imageSettings?: ImageSettings;
  framework: FrameworkMetadata;
};

次のトピックでは、デプロイマニフェストの各属性の詳細と使用法について説明します。

バージョン属性の使用

version 属性は、実装しようとしているデプロイ仕様のバージョンを定義します。現在、Amplify ホスティングのデプロイ仕様の唯一のバージョンはバージョン 1 です。次のJSON例は、 version 属性の使用方法を示しています。

"version": 1

ルート属性の使用

routes 属性により、フレームワークは Amplify ホスティングのルーティングルールのプリミティブを利用できるようになります。ルーティングルールは、着信リクエストのパスをデプロイバンドル内の特定のターゲットにルーティングするメカニズムを提供します。ルーティングルールは着信リクエストの宛先のみを決定し、リクエストが書き換えルールとリダイレクトルールによって変換された後に適用されます。Amplify ホスティングが書き換えとリダイレクトを処理する方法の詳細については、「Amplify アプリケーションのリダイレクトと書き換えの設定」を参照してください。

ルーティングルールは、リクエストを書き換えたり、変換したりしません。着信リクエストがルートのパスパターンと一致する場合、リクエストはそのままルートのターゲットにルーティングされます。

routes 配列で指定されたルーティングルールは、次のルールに準拠する必要があります。

次のオブジェクト定義は、Route オブジェクトの設定を示しています。

type Route = {
  path: string;
  target: Target;
  fallback?: Target;
}

次の表では、Route オブジェクトのプロパティについて説明します。

次のオブジェクト定義は、Target オブジェクトの設定を示しています。

type Target = {
  kind: TargetKind;
  src?: string;
  cacheControl?: string;
}

次の表では、Target オブジェクトのプロパティについて説明します。

次のオブジェクト定義は、TargetKind 列挙型の使用法を示しています。

enum TargetKind {
  Static = "Static",
  Compute = "Compute",
  ImageOptimization = "ImageOptimization"
}

次のリストは、TargetKind 列挙型の有効な値を指定します。

次のJSON例は、複数のルーティングルールが指定されている routes 属性の使用方法を示しています。

"routes": [
    {
      "path": "/_nuxt/image",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=3600, immutable"
      }
    },
    {
      "path": "/_nuxt/builds/meta/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/builds/*",
      "target": {
        "cacheControl": "public, max-age=1, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/*.*",
      "target": {
        "kind": "Static"
      },
      "fallback": {
        "kind": "Compute",
        "src": "default"
      }
    },
    {
      "path": "/*",
      "target": {
        "kind": "Compute",
        "src": "default"
      }
    }
  ]

デプロイマニフェストでのルーティングルールの指定の詳細については、「ルーティングルールの設定に関するベストプラクティス」を参照してください。

computeResources 属性の使用

computeResources 属性により、フレームワークは、プロビジョニングされたコンピューティングリソースに関するメタデータを提供できるようになります。あらゆるコンピューティングリソースには、対応するルートが関連付けられている必要があります。

次のオブジェクト定義は、ComputeResource オブジェクトの使用法を示しています。

type ComputeResource = {
  name: string;
  runtime: ComputeRuntime;
  entrypoint: string;
};

type ComputeRuntime = 'nodejs16.x' | 'nodejs18.x' | 'nodejs20.x';

次の表では、ComputeResource オブジェクトのプロパティについて説明します。

次のようなディレクトリ構造があるとします。

.amplify-hosting
|---compute
|   |---default
|       |---index.js

computeResource 属性JSONの は次のようになります。

"computeResources": [
    {
      "name": "default",
      "runtime": "nodejs16.x",
      "entrypoint": "index.js",
    }
  ]

imageSettings 属性の使用

imageSettings 属性を使用すると、フレームワークは画像の最適化のプリミティブの動作をカスタマイズでき、実行時における画像のオンデマンド最適化を提供します。

次のオブジェクト定義は、ImageSettings オブジェクトの使用法を示しています。

type ImageSettings = {
  sizes: number[];
  domains: string[];
  remotePatterns: RemotePattern[];
  formats: ImageFormat[];
  minumumCacheTTL: number;
  dangerouslyAllowSVG: boolean;
};

type ImageFormat = 'image/avif' | 'image/webp' | 'image/png' | 'image/jpeg';

次の表では、ImageSettings オブジェクトのプロパティについて説明します。

次のオブジェクト定義は、RemotePattern オブジェクトの使用法を示しています。

type RemotePattern = {
  protocol?: 'http' | 'https';
  hostname: string;
  port?: string;
  pathname?: string;
}

次の表では、RemotePattern オブジェクトのプロパティについて説明します。

次の例は、imageSettings 属性を示しています。

"imageSettings": { 
    "sizes": [
      100,
      200
    ],
    "domains": [
      "example.com"
    ],
    "remotePatterns": [
      {
        "protocol": "https",
        "hostname": "example.com",
        "port": "",
        "pathname": "/**",
      }
    ],
    "formats": [
      "image/webp"
    ],
    "minumumCacheTTL": 60,
    "dangerouslyAllowSVG": false
  }

フレームワーク属性の使用

framework 属性を使用してフレームワークのメタデータを指定します。

次のオブジェクト定義は、FrameworkMetadata オブジェクトの設定を示しています。

type FrameworkMetadata = {
  name: string;
  version: string;
}

次の表では、FrameworkMetadata オブジェクトのプロパティについて説明します。

ルーティングルールの設定に関するベストプラクティス

ルーティングルールは、着信リクエストのパスをデプロイバンドル内の特定のターゲットにルーティングするメカニズムを提供します。デプロイバンドルでは、フレームワークの作成者は、次のターゲットのいずれかにデプロイされるファイルをビルド出力に出力できます:

また、フレームワークの作成者は、デプロイマニフェストファイルでルーティングルールの配列も提供します。配列内の各ルールは、一致が見つかるまで、シーケンシャルトラバーサル順序で着信リクエストと照合されます。一致するルールがある場合、リクエストは一致ルールで指定されたターゲットにルーティングされます。オプションで、ルールごとにフォールバックターゲットを指定できます。元のターゲットが 404 エラーを返した場合、リクエストはフォールバックターゲットにルーティングされます。

デプロイ仕様では、トラバーサル順序の最後のルールがキャッチオールルールである必要があります。キャッチオールルールは /* パスで指定されます。着信リクエストがルーティングルールの配列内の以前のルートのいずれとも一致しない場合、リクエストはキャッチオールルールのターゲットにルーティングされます。

のようなSSRフレームワークの場合 Nuxt.js、キャッチオールルールターゲットはコンピューティングプリミティブである必要があります。これは、SSRアプリケーションには、ビルド時に予測できないルートを含むサーバー側でレンダリングされたページがあるためです。たとえば、Nuxt.js アプリケーションには ページがあります。/blog/[slug]ここで、 [slug]は動的ルートパラメータです。キャッチオールルールのターゲットは、リクエストをこれらのページにルーティングする唯一の方法です。

対照的に、特定のパスパターンを使用して、ビルド時に既知のルートをターゲットにすることができます。例えば、 などです Nuxt.js は/_nuxtパスから静的アセットを提供します。これは、リクエストを静的アセットプリミティブにルーティングする特定のルーティングルールによって /_nuxt/* パスをターゲットとすることができることを意味します。

パブリックフォルダのルーティング

ほとんどのSSRフレームワークは、publicフォルダから変更可能な静的アセットを提供する機能を提供します。favicon.ico や などのファイルは、通常 robots.txt publicフォルダ内に保持され、アプリケーションのルート から提供されますURL。例えば、favicon.ico ファイルは https://example.com/favicon.ico から提供されます。これらのファイルには予測可能なパスパターンがないことに留意してください。それらは、ほぼ完全にファイル名によって決まります。public フォルダ内のファイルをターゲットにする唯一の方法は、キャッチオールルートを使用することです。ただし、キャッチオールルートのターゲットはコンピューティングプリミティブである必要があります。

public フォルダを管理するには、次のいずれかのアプローチをお勧めします。

キャッチオールフォールバックルーティング

などのSSRフレームワークの場合 Nuxt.jsでは、コンピューティングプリミティブターゲットにキャッチオールルートが指定されている場合、フレームワークの作成者は、キャッチオールルートの静的フォールバックを指定してpublicフォルダルーティングの問題を解決することを検討できます。しかし、このタイプのルーティングルールでは、サーバーサイドレンダリングされた 404 ページが壊れます。例えば、存在しないページにエンドユーザーがアクセスすると、アプリケーションはステータスコード 404 で 404 ページを表示します。しかし、キャッチオールルートに静的フォールバックがある場合、404 ページはレンダリングされません。代わりに、リクエストは静的プリミティブにフォールバックし、依然として 404 ステータスコードで終了しますが、404 ページはレンダリングされません。

{
    "path": "/*",
    "target": {
        "kind": "Compute",
        "src": "default"
    },
    "fallback": {
        "kind": "Static"
    }
}

ベースパスルーティング

アプリケーションのベースパスを変更する機能を提供するフレームワークは、.amplify-hosting/static ディレクトリ内の静的アセットへのベースパスを先頭に付加することが想定されます。例えば、ベースパスが /folder1/folder2 である場合、main.css という静的アセットのビルド出力は .amplify-hosting/static/folder1/folder2/main.css になります。

これは、ベースパスを反映するためにルーティングルールも更新する必要があることを意味します。例えば、ベースパスが /folder1/folder2 である場合、public フォルダ内の静的アセットのルーティングルールは次のようになります。

{
    "path": "/folder1/folder2/*.*",
    "target": {
        "kind": "Static"
    }
}

同様に、サーバー側のルートにもベースパスを先頭に付加する必要があります。例えば、ベースパスが /folder1/folder2 である場合、/api ルートのルーティングルールは次のようになります。

{
    "path": "/folder1/folder2/api/*",
    "target": {
        "kind": "Compute",
        "src": "default"
    }
}

ただし、ベースパスをキャッチオールルートの先頭に付加しないでください。例えば、ベースパスが /folder1/folder2 である場合、キャッチオールルートは次のようになります。

{
    "path": "/*",
    "target": {
        "kind": "Compute",
        "src": "default"
    }
}

Nuxt.js ルートの例

ルーティングルールを指定する方法を示す Nuxt アプリケーションのサンプル deploy-manifest.json ファイルを次に示します。

{
  "version": 1,
  "routes": [
    {
      "path": "/_nuxt/image",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=3600, immutable"
      }
    },
    {
      "path": "/_nuxt/builds/meta/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/builds/*",
      "target": {
        "cacheControl": "public, max-age=1, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/*.*",
      "target": {
        "kind": "Static"
      },
      "fallback": {
        "kind": "Compute",
        "src": "default"
      }
    },
    {
      "path": "/*",
      "target": {
        "kind": "Compute",
        "src": "default"
      }
    }
  ],
  "computeResources": [
    {
      "name": "default",
      "entrypoint": "server.js",
      "runtime": "nodejs18.x"
    }
  ],
  "framework": {
    "name": "nuxt",
    "version": "3.8.1"
  }
}

ベースパスを含むルーティングルールを指定する方法を示す Nuxt のサンプル deploy-manifest.json ファイルを次に示します。

{
  "version": 1,
  "routes": [
    {
      "path": "/base-path/_nuxt/image",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=3600, immutable"
      }
    },
    {
      "path": "/base-path/_nuxt/builds/meta/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/base-path/_nuxt/builds/*",
      "target": {
        "cacheControl": "public, max-age=1, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/base-path/_nuxt/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/base-path/*.*",
      "target": {
        "kind": "Static"
      },
      "fallback": {
        "kind": "Compute",
        "src": "default"
      }
    },
    {
      "path": "/*",
      "target": {
        "kind": "Compute",
        "src": "default"
      }
    }
  ],
  "computeResources": [
    {
      "name": "default",
      "entrypoint": "server.js",
      "runtime": "nodejs18.x"
    }
  ],
  "framework": {
    "name": "nuxt",
    "version": "3.8.1"
  }
}

routes 属性の使用に関する詳細については、「ルート属性の使用」を参照してください。