ファイル/添付ファイルの操作
StorageカテゴリとGraphQL APIカテゴリを組み合わせて、特定のレコードに画像や動画などのファイルを関連付けることができます。例えば、プロフィール画像を持つUserモデルや、関連する画像を持つPostモデルを作成することができます。AmplifyのGraphQL APIおよびStorageカテゴリを使用すると、モデル自体の中でファイルを参照して関連付けを作成することができます。
プロジェクトのセットアップ
クイックスタートガイドの手順に従ってプロジェクトをセットアップしてください。
モデルの定義
amplify/data/resource.tsを開き、以下のモデルを追加してください：
import { type ClientSchema, a, defineData } from "@aws-amplify/backend";
const schema = a.schema({ Song: a .model({ id: a.id().required(), name: a.string().required(), coverArtPath: a.string(), }) .authorization((allow) => [allow.publicApiKey()]),});
export type Schema = ClientSchema<typeof schema>;
export const data = defineData({ schema, authorizationModes: { defaultAuthorizationMode: "apiKey",
apiKeyAuthorizationMode: { expiresInDays: 30, }, },});Storageのセットアップ
次に、Storageを設定し、アプリケーションのすべての認証済み（サインイン済み）ユーザーにアクセスを許可します。amplify/storage/resource.tsファイルを作成し、以下のコードを追加してください。これにより、ファイルアクセスがサインイン済みユーザーのみに制限されます。
import { defineStorage } from "@aws-amplify/backend";
export const storage = defineStorage({ name: "amplify-gen2-files", access: (allow) => ({ "images/*": [allow.authenticated.to(["read", "write", "delete"])], }),});以下のようにamplify/backend.tsファイルでStorageを設定してください：
import { defineBackend } from "@aws-amplify/backend";import { auth } from "./auth/resource";import { data } from "./data/resource";import { storage } from "./storage/resource";
export const backend = defineBackend({ auth, data, storage,});認可の設定
すべてのデータとファイルをパブリックにアクセス可能にする場合を除き、アプリケーションはStorageとDataの両方に対して読み取りおよび書き込みのための認可クレデンシャルが必要です。
StorageカテゴリとDataカテゴリはそれぞれ独自の認可パターンに基づいてデータアクセスを管理します。つまり、各カテゴリに対して適切な認可ロールを設定する必要があります。両カテゴリはAuthカテゴリを通じて設定された同じアクセスクレデンシャルを共有していますが、互いに独立して動作します。例えば、DataにAllow.authenticated()を追加しても、StorageカテゴリのファイルアクセスはGuardされません。同様に、Storageカテゴリに認可ルールを追加しても、APIのデータアクセスはGuardされません。
Storageを設定すると、AmplifyはCognito IDプールロールを使用してバケット上に適切なIAMポリシーを設定します。その後、認証済みユーザーとゲストユーザーがこれらのレベル内で限定的な権限を付与されるように、CRUDベース（作成、更新、読み取り、削除）の権限を追加することもできます。この設定を追加した後も、すべてのStorageアクセスはデフォルトでguestのままです。 誤ってパブリックアクセスされないよう、StorageアクセスレベルはStorageオブジェクト上でグローバルに設定するか、個々の関数呼び出しで設定する必要があります。このガイドでは前者のアプローチを使用し、すべてのStorageアクセスをauthenticatedユーザーに設定します。
各カテゴリの認可ルールを個別に設定できる機能により、データアクセスのより細かいコントロールが可能になり、柔軟性が高まります。認可パターンを混在させる必要があるシナリオでは、個々のStorage関数呼び出しにアクセスレベルを設定してください。例えば、所有者のみがアクセスすべきファイル（個人ファイルなど）にはentity_id CRUDアクセスを、ログイン済みの全ユーザーが共通ファイル（共有フォトアルバムの画像など）を閲覧できるようにするにはauthenticated読み取りアクセスを、全ユーザーがファイル（パブリックプロフィール画像など）を閲覧できるようにするにはguest読み取りアクセスを使用することができます。
Storageの認可レベルの設定方法の詳細については、Storageのドキュメントを参照してください。Dataの認可設定については、APIのドキュメントを参照してください。
関連ファイルを持つレコードの作成
Amplify Dataクライアントを使用してレコードを作成し、Storageにファイルをアップロードし、最後にレコードをアップロードしたファイルと関連付けることができます。以下の例では、Amplify Dataクライアントと、Amplify StorageライブラリのヘルパーであるuploudDataとgetUrlを使用して、レコードを作成し、ファイルをレコードに関連付けます。
関連レコードのファイルの追加または更新
ファイルをレコードに関連付けるには、Storageのアップロードで返されたパスでレコードを更新します。以下の例では、Storageを使用してファイルをアップロードし、ファイルのパスでレコードを更新してから、画像をダウンロードするための署名付きURLを取得します。画像がすでにレコードに関連付けられている場合、レコードは新しい画像で更新されます。
レコードのクエリと関連ファイルの取得
レコードに関連付けられたファイルを取得するには、まずレコードをクエリし、次にStorageを使用して署名付きURLを取得します。署名付きURLを使用してファイルをダウンロードしたり、画像を表示したりすることができます：
APIレコードに関連するファイルの削除と除去
StorageファイルとGraphQL APIを操作する際によく使われる削除ワークフローは3つあります：
- ファイルの関連付けを削除し、ファイルとレコードの両方を保持し続ける。
- レコードの関連付けを削除してファイルを削除する。
- ファイルとレコードの両方を削除する。
ファイルの関連付けを削除し、ファイルとレコードの両方を保持し続ける
以下の例では、レコードからファイルの関連付けを削除しますが、S3からファイルは削除せず、データベースのレコードも削除しません。
レコードの関連付けを削除してファイルを削除する
以下の例では、レコードからファイルを削除し、次にS3からファイルを削除します：
ファイルとレコードの両方を削除する
複数ファイルの操作
ユーザープロフィールに複数の画像を持たせるなど、1つのレコードに複数のファイルを追加したい場合があります。これを行うには、レコードにファイルキーのリストを追加できます。以下の例では、レコードにファイルキーのリストを追加します：
複数のファイルをデータモデルに関連付けるGraphQLスキーマ
amplify/data/resource.tsファイルに以下のモデルを追加してください。
const schema = a.schema({ PhotoAlbum: a .model({ id: a.id().required(), name: a.string().required(), imagePaths: a.string().array(), }) .authorization((allow) => [allow.publicApiKey()]),});複数のファイルを操作する際のCRUD操作は、単一のファイルキーではなくファイルキーのリストを操作する点を除いて、単一ファイルを操作する場合と同じです。
複数の関連ファイルを持つレコードの作成
まずGraphQL APIを使用してレコードを作成し、次にStorageにファイルをアップロードし、最後にレコードとファイルの関連付けを追加します。
関連レコードへの新しいファイルの追加
レコードに追加のファイルを関連付けるには、Storageのアップロードで返されたパスでレコードを更新します。
関連レコードのファイルの更新
関連レコードのファイルを更新する操作は、単一ファイルレコードのファイルを更新する場合と同じですが、ファイルキーのリストを更新する必要がある点が異なります。
レコードのクエリと関連ファイルの取得
レコードに関連付けられたファイルを取得するには、まずレコードをクエリし、次にStorageを使用してすべての署名付きURLを取得します。
APIレコードに関連するファイルの削除と除去
APIレコードに関連するファイルの削除と除去のワークフローは、単一ファイルを操作する場合と同じですが、削除を実行する際はファイルパスのリストを反復処理して各ファイルに対してStorage.remove()を呼び出す必要があります。
ファイルの関連付けを削除し、ファイルとレコードの両方を保持し続ける
レコードの関連付けを削除してファイルを削除する
レコードとすべての関連ファイルの削除
レコードとファイルを操作する際のデータ整合性
このドキュメントで推奨するアクセスパターンは、削除されたファイルを除去しようとしますが、存在しないファイルを参照するレコードを残すよりも、孤立したファイルを残す方を優先します。これにより、クライアントが存在しないStorageファイルを取得しようとすることが_ほとんどない_ことが保証され、読み取りレイテンシが最適化されます。ただし、ファイルを削除するアプリケーションでは、_デバイス上の_レコードが存在しないファイルを参照する可能性が本質的に生じます。
一例として、APIレコードを作成し、Storageファイルをそのレコードに関連付け、ファイルの署名付きURLを取得する場合があります。「デバイスA」がGraphQL APIを呼び出してAPI_Record_1を作成し、次にそのレコードをFirst_Photoと関連付けます。「デバイスA」が署名付きURLを取得しようとする直前に、「デバイスB」がAPI_Record_1をクエリし、First_Photoを削除して、それに応じてレコードを更新する可能性があります。しかし、「デバイスA」はまだ古いAPI_Record_1を使用しており、そのレコードはすでに存在しないファイルを参照しています。共有グローバル状態がすべての段階で正しく同期されているにもかかわらず、個々のデバイス（「デバイスA」）には存在しないファイルを参照する古いレコードが残っています。同様の問題が更新時にも発生する可能性があります。アプリによっては、リアルタイムデータ / GraphQLサブスクリプションを使用することで、これらの不一致を_さらに_最小化できる場合があります。
これらの不一致がいつ発生するかを理解し、そのようなケースに対して意味のあるエラーハンドリングを追加することが重要です。このガイドには、包括的なエラーハンドリング、リアルタイムサブスクリプション、古くなったレコードの再クエリ、失敗した操作の再試行は含まれていません。ただし、これらはすべて本番レベルのアプリケーションにとって重要な考慮事項です。