APIリファレンス関数revalidateTag

revalidateTag

revalidateTag を使用すると、特定のキャッシュタグのキャッシュデータをオンデマンドで無効化できます。

この関数は、ブログ記事、製品カタログ、ドキュメントなど、更新の遅延が許容されるコンテンツに最適です。ユーザーは、バックグラウンドで新しいデータがロードされている間、古いコンテンツを受け取ります。

使用方法

revalidateTag は、サーバー関数およびルートハンドラーで呼び出すことができます。

revalidateTag は、サーバー環境でのみ機能するため、クライアントコンポーネントやプロキシでは呼び出すことができません。

再検証の動作

再検証の動作は、2番目の引数を指定するかどうかによって異なります。

profile="max" (推奨) の場合: タグのエントリは無効としてマークされ、次にそのタグを持つリソースにアクセスしたときに、stale-while-revalidate セマンティクスが使用されます。これは、古いコンテンツがバックグラウンドで新しいコンテンツをフェッチしている間に提供されることを意味します。
カスタムキャッシュライフプロファイルの場合: 高度な使用法では、アプリケーションで定義された任意のキャッシュライフプロファイルを指定して、特定のキャッシュ要件に合わせたカスタム再検証動作を可能にすることができます。
2番目の引数なし (非推奨) の場合: タグのエントリは直ちに期限切れになり、そのリソースへの次のリクエストはブロック再検証/キャッシュミスになります。この動作は現在非推奨であり、profile="max" を使用するか、updateTag に移行する必要があります。

注意: profile="max" を使用する場合、revalidateTag はタグ付きデータを無効としてマークしますが、新しいデータは、そのタグを使用するページが次にアクセスされたときにのみフェッチされます。これは、revalidateTag を呼び出しても、一度に多くの再検証が即座にトリガーされるわけではないことを意味します。無効化は、そのタグを使用するいずれかのページが次にアクセスされたときにのみ発生します。

Parameters

revalidateTag(tag: string, profile?: string | { expire?: number }): void;

tag: 再検証したいデータに関連付けられたキャッシュタグを表す文字列。256文字を超えることはできません。この値は、大文字と小文字を区別します。
profile: 再検証の動作を指定する文字列。推奨される値は "max" で、stale-while-revalidate セマンティクスを提供します。または、cacheLife で定義された他のデフォルトまたはカスタムプロファイルのいずれかを使用できます。あるいは、カスタムの有効期限動作のために expire プロパティを持つオブジェクトを渡すこともできます。

タグは、まずキャッシュデータに割り当てる必要があります。これは次の2つの方法で行うことができます。

外部APIリクエストのキャッシュのために、fetch で next.tags オプションを使用する

fetch(url, { next: { tags: ['posts'] } })

'use cache' ディレクティブを使用して、キャッシュされた関数またはコンポーネント内で cacheTag を使用する

import { cacheTag } from 'next/cache'
 
async function getData() {
  'use cache'
  cacheTag('posts')
  // ...
}

戻り値

revalidateTag は値を返しません。

`revalidatePath`との関係

revalidateTag は、それらのタグを使用するすべてのページにわたって特定のタグを持つデータを無効化しますが、revalidatePath は特定のページまたはレイアウトパスを無効化します。

注意: これらの関数は異なる目的を果たし、包括的なデータの一貫性のために一緒に使用する必要がある場合があります。詳細な例と考慮事項については、revalidateTagおよびupdateTagとの関係を参照してください。

例

以下の例では、さまざまなコンテキストで revalidateTag を使用する方法を示しています。どちらの場合も、profile="max" を使用してデータを無効としてマークし、stale-while-revalidate セマンティクスを使用しています。これは、ほとんどのユースケースで推奨されるアプローチです。

サーバーアクション

'use server'
 
import { revalidateTag } from 'next/cache'
 
export default async function submit() {
  await addPost()
  revalidateTag('posts', 'max')
}

ルートハンドラー

import type { NextRequest } from 'next/server'
import { revalidateTag } from 'next/cache'
 
export async function GET(request: NextRequest) {
  const tag = request.nextUrl.searchParams.get('tag')
 
  if (tag) {
    revalidateTag(tag, 'max')
    return Response.json({ revalidated: true, now: Date.now() })
  }
 
  return Response.json({
    revalidated: false,
    now: Date.now(),
    message: 'Missing tag to revalidate',
  })
}

注意: 即時期限切れが必要なWebhookまたはサードパーティサービスの場合、2番目の引数として { expire: 0 } を渡すことができます: revalidateTag(tag, { expire: 0 })。このパターンは、外部システムがルートハンドラーを呼び出し、データが直ちに期限切れになる必要がある場合に必要です。他のすべてのケースでは、即時更新のためにサーバーアクションで updateTag を使用することが推奨されます。

役に立ちましたか？