アプリケーションデータの読み取り
Amplify Dataクライアントを使用してアプリケーションデータを読み取ることができます。このガイドでは、データの読み取りとデータの取得の違い、必要なデータだけを取得するためにクエリ結果をフィルタリングする方法、および結果をページネーションしてデータをより管理しやすくする方法を確認します。また、必要に応じてこれらのリクエストをキャンセルする方法も説明します。
開始する前に、以下が必要です:
- APIに接続されたアプリケーション
- 表示するために既に作成されたデータ
データをリストして取得する
クエリはAPIを通じてデータを読み取るために使用され、listおよびget操作が含まれます。Amplify Dataは、スキーマ内の任意のa.model()タイプに対してlistおよびgetクエリを自動的に作成します。listクエリは、特定のレコードの識別子を指定する必要なく、Todoアイテムなどの複数のアイテムを取得します。これは、アイテムの概要または要約を取得したり、list操作を拡張して特定の条件でアイテムをフィルタリングしたりするのに最適です。識別子で単一エントリをクエリしたい場合は、getを使用して特定のTodoアイテムを取得します。
バックエンドデータスキーマを使用してDataクライアントを生成することで、アイテムをリストできます。その後、目的のモデルのアイテムをリストできます:
import { generateClient } from 'aws-amplify/data';import { type Schema } from '@/amplify/data/resource';
const client = generateClient<Schema>();
// list itemsconst { data: todos, errors } = await client.models.Todo.list();
// get a specific itemconst { data: todo, errors } = await client.models.Todo.get({ id: '...',});トラブルシューティング認可されていないエラーのトラブルシューティング
各APIリクエストは認可モードを使用します。認可されていないエラーが発生した場合、認可モードを更新する必要があります。amplify/data/resource.tsファイルで定義されたデフォルト認可モードをオーバーライドするには、authModeプロパティをリクエストまたはクライアントに渡します。次の例は、カスタム認可モードでデータを変更する方法を示しています:
import { generateClient } from 'aws-amplify/data';import { type Schema } from '@/amplify/data/resource';
const client = generateClient<Schema>();
const { errors, data: todos } = await client.models.Todo.list({ authMode: 'apiKey',});リストクエリをフィルタリングする
データが増えるにつれて、リストクエリをページネーションする必要があります。幸い、これはAmplify Dataに既に組み込まれています。
import { generateClient } from 'aws-amplify/data';import { type Schema } from '@/amplify/data/resource';
const client = generateClient<Schema>();
const { data: todos, errors } = await client.models.Todo.list({ filter: { content: { beginsWith: 'hello' } }});複合フィルタ
and、or、およびnotブール論理でフィルタを組み合わせることができます。filterは、これらのフィールドに関して再帰的であることに注意してください。たとえば、priorityの値が1_または_2のフィルタリングが必要な場合、以下のようにします:
import { generateClient } from 'aws-amplify/data';import { type Schema } from '@/amplify/data/resource';
const client = generateClient<Schema>();
const { data: todos, errors } = await client.models.Todo.list({ filter: { or: [ { priority: { eq: '1' } }, { priority: { eq: '2' } } ] }});priorityが1と2のクエリはブール論理であり、自然言語ではないため、結果が返されないことに注意してください。
リストクエリをページネーションする
リストクエリの結果をページネーションするには、nextTokenおよびlimit入力変数を設定した後続のリストクエリリクエストを作成します。limit変数は、返される結果の数を制限します。レスポンスには、データの次のページをリクエストするために使用できるnextTokenが含まれます。nextTokenは、これらのフィルタで作成された次のクエリの開始アイテムのカーソルを表す非常に長い文字列です。
import { generateClient } from 'aws-amplify/data';import { type Schema } from '@/amplify/data/resource';
const client = generateClient<Schema>();
const { data: todos, nextToken, // 返された nextToken が `null` になるまで、このAPI呼び出しを nextToken で繰り返します errors} = await client.models.Todo.list({ limit: 100, // デフォルト値は100です nextToken: 'eyJ2ZXJzaW9uejE1a2...' // 前の nextToken});Reactアプリケーションを構築している場合、Amplify UIのusePaginationフックを使用して、ページネーションのユーザーエクスペリエンス管理を支援できます。
import * as React from 'react';import { Pagination } from '@aws-amplify/ui-react';
export const PaginationHasMorePagesExample = () => { const [pageTokens, setPageTokens] = React.useState([null]); const [currentPageIndex, setCurrentPageIndex] = React.useState(1); const [hasMorePages, setHasMorePages] = React.useState(true);
const handleNextPage = async () => { if (hasMorePages && currentPageIndex === pageTokens.length) { const { data: todos, nextToken } = await client.models.Todo.list({ nextToken: pageTokens[pageTokens.length - 1] });
if (!nextToken) { setHasMorePages(false); }
setPageTokens([...pageTokens, nextToken]); }
setCurrentPageIndex(currentPageIndex + 1); };
return ( <Pagination currentPage={currentPageIndex} totalPages={pageTokens.length} hasMorePages={hasMorePages} onNext={handleNextPage} onPrevious={() => setCurrentPageIndex(currentPageIndex - 1)} onChange={(pageIndex) => setCurrentPageIndex(pageIndex)} /> );};カスタム選択セットで必要なデータのみを取得する
ビジネスドメインモデルには、多くのフィールドを持つ多くのモデルが含まれている可能性があります。ただし、アプリケーションは通常、異なるコンポーネントまたは画面の要件を満たすためにデータまたはフィールドのサブセットのみを必要とします。モデルとその関係のサブセットを取得するメカニズムが必要です。このメカニズムは、必要なデータのみを転送することで、画面とコンポーネントのデータ使用を最適化するのに役立ちます。この機能を備えることで、アプリケーションのデータ効率、レイテンシ、およびエンドユーザーの認識されたパフォーマンスが向上します。
カスタム選択セットを使用すると、消費者がコール単位で取得したいフィールドを指定できます。これは、データを返すすべての操作(CRUDL +observeQuery)で可能です。目的のフィールドは「ドット表記」を使用して、強く型付けされた方法(IntelliSenseで発見可能)で指定されます。
// CRUDL: .create, .get, .update, .delete, .list, .observeQuery の全てで同じやり方const { data: blogWithSubsetOfData, errors } = await client.models.Blog.get( { id: blog.id }, { selectionSet: ['author.email', 'posts.*'], });Amplify DataのTypeScriptタイプヘルパー
TypeScriptを使用する場合、タイプジェネリックのためにデータモデルタイプを指定する必要があることが頻繁にあります。
たとえば、ReactのuseStateでは、コンポーネントコード内でステートを使用したタイプセーフティを確保するためにTypeScriptで型を指定します。Schema["MODEL_NAME"]["type"]パターンを使用して、バックエンドAPIから返されるデータモデルの形状のTypeScriptタイプを取得します。
import { type Schema } from '@/amplify/data/resource';
type Post = Schema['Post']['type'];
const [posts, setPosts] = useState<Post[]>([]);Schema["MODEL_NAME"]["type"]タイプをSelectionSetヘルパータイプと組み合わせて、selectionSetパラメータを使用するAPIリクエストの戻り型を記述できます:
import type { SelectionSet } from 'aws-amplify/data';import type { Schema } from '../amplify/data/resource';
const selectionSet = ['content', 'blog.author.*', 'comments.*'] as const;type PostWithComments = SelectionSet<Schema['Post']['type'], typeof selectionSet>;
// ...const [posts, setPosts] = useState<PostWithComments[]>([]);
const fetchPosts = async () => { const { data: postsWithComments } = await client.models.Post.list({ selectionSet, }); setPosts(postsWithComments);}リクエストの読み取りをキャンセルする
.list(...)または.get(...)によって返されるクエリリクエストプロミスで.cancelを呼び出すことで、任意のクエリAPIリクエストをキャンセルできます。
const promise = client.models.Todo.list();// ^ 注: リクエストをawaitしていなく、プロミスを返しています
try { await promise;} catch (error) { console.log(error); // リクエストがキャンセルされたことが原因であるエラーの場合、ここで確認できます。 if (client.isCancelError(error)) { console.log(error.message); // "my message for cancellation" // ユーザーキャンセルロジックを処理します }}...
// 上記のリクエストをキャンセルするにはclient.cancel(promise, "my message for cancellation");.list()または.get()から返されるプロミスが変更されていないことを確認する必要があります。通常、非同期関数は返されるプロミスを別のプロミスにラップします。たとえば、以下は機能しません:
async function makeAPICall() { return client.models.Todo.list();}const promise = makeAPICall();
// 以下はリクエストをキャンセルしません。client.cancel(promise, 'my error message');結論
おめでとうございます! アプリケーションデータの読み取りガイドを完了しました。このガイドでは、getおよびlistクエリを通じてデータを読み取る方法を学びました。
次のステップ
推奨される次のステップには、データの変更を監視するためにリアルタイムイベントをサブスクライブしたり、さらなるデータの情報アーキテクチャを構築および定をカスタマイズしたりすることが含まれます。この作業に役立つリソースには以下が含まれます: