ナビゲーションメニューAPIの基本

LiferayのREST APIは、Liferayのナビゲーションメニューにサービスを提供します。 APIを使用してナビゲーションメニューを作成および編集できます。 まずは、新しいナビゲーションメニューを追加する例を見てみましょう。

注

Liferay DXP 2025.Q2+ ナビゲーションメニューAPIは、これらの要素を参照するために外部参照コード（ERC）を使用するようになりました。これにより、インスタンス間で一貫した識別が可能になり、コンテンツ管理と移植性を向上させるためのバッチエクスポート/インポートがサポートされます。

重要

Liferay 2026.Q1+ナビゲーション メニューのエンドポイントが、サイト スコープの操作とバッチ処理との整合性を高めるため、headless-deliveryからheadless-admin-site に移動されました。

非推奨: ヘッドレス配信 エンドポイントは 非推奨です。 既存の統合機能は、後方互換性のために引き続き動作します。 新しい統合には、 headless-admin-site API を使用してください。

ERC要件: 新しいエンドポイントは、外部参照コード（ERC）によってサイトとナビゲーションメニューを識別します。

バッチサポート: headless-admin-site API は、ナビゲーションメニューのバッチエンジンのインポートとエクスポートをサポートしています。

ナビゲーションメニューの追加

新しいLiferay DXPインスタンスを起動し、以下を実行します。

docker run -it -m 8g -p 8080:8080 liferay/dxp:2025.q1.6-lts

http://localhost:8080 に、メールアドレス [e-mail] とパスワード test を使用して Liferay にサインインします。 プロンプトが表示されたら、パスワードを learnに変更します。

次に、以下の手順に従います。

1. ダウンロードして解凍します ナビゲーションメニューAPIの基本。

   curl https://resources.learn.liferay.com/examples/liferay-p7s4.zip -O
   

   unzip liferay-p7s4.zip
   

2. サイトIDを見つけてください。 以下のさまざまなサービス呼び出しで使用してください。

3. cURLスクリプトを使用して、サイトに新しいナビゲーションメニューを追加します。 コマンドラインで、curlフォルダに移動します。 NavigationMenus_POST_ToSites.sh スクリプトを、 サイト ID をパラメータとして実行します。

   ./NavigationMenus_POST_ToSites.sh 1234
   

   JSONのレスポンスには、新しいナビゲーションメニューが追加されたことが示されています。

   {
   "creator" : {
      "additionalName" : "",
      "contentType" : "UserAccount",
      "familyName" : "Test",
      "givenName" : "Test",
      "id" : 20129,
      "name" : "Test Test"
   },
   "dateCreated" : "2021-09-09T21:41:31Z",
   "dateModified" : "2021-09-09T21:41:31Z",
   "id" : 40131,
   "name" : "Foo",
   "navigationMenuItems" : [ ],
   "siteId" : 20125
   }
   

4. 管理メニュー → サイトビルダー → ナビゲーションメニュー に移動して、ナビゲーションメニューアプリケーションに移動します。 新しいナビゲーションメニューが追加されたことを確認してください。

   

5. RESTサービスは、Javaクライアントを使って呼び出すこともできます。 curl フォルダから、 java フォルダに移動します。 以下のコマンドでソースファイルをコンパイルします。

   javac -classpath .:* *.java
   

6. 以下のコマンドで NavigationMenus_POST_ToSites クラスを実行します。 siteId の値を、ご自身のサイト ID に置き換えてください。

   java -classpath .:* -DsiteId=1234 NavigationMenus_POST_ToSites
   

cURLコマンドの検証

NavigationMenus_POST_ToSites.sh スクリプトは、cURL コマンドを使用して REST サービスを呼び出します。

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus" \
	--data-raw '
		{
			"name": "Foo"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "[e-mail]:learn"

ここでは、コマンドの引数を紹介します。

引数	説明
-H "Content-Type: application/json"	リクエストボディのフォーマットがJSONであることを示します。
-X POST	指定されたエンドポイントで起動するHTTPメソッド
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus"	RESTサービスのエンドポイント
-d "{\"name\": \"Foo\"}"	お客様が掲載を希望するデータ
-u "[e-mail]:learn"	基本的な認証情報

注

上記のエンドポイントは、後方互換性のために非推奨の ヘッドレス配信 パスを使用しています。 2026.Q1+ の新しい統合については、代わりに headless-admin-site エンドポイントを使用してください。

注

ここでは、デモのために基本的な認証を使用しています。 本番環境では、 OAuth2 を介してユーザーを認証する必要があります。 OAuth2 を使用する React アプリケーションの例については、 OAuth2 を使用してユーザーを認証する を参照してください。

他のcURLコマンドも同様のJSON引数を使用しています。

Javaクラスを調べる

NavigationMenus_POST_ToSites.java クラスは、 NavigationMenuResource サービスを呼び出すことでナビゲーション メニューを追加します。

public static void main(String[] args) throws Exception {
	NavigationMenuResource.Builder builder =
		NavigationMenuResource.builder();

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	NavigationMenu navigationMenu =
		navigationMenuResource.postSiteNavigationMenu(
			Long.valueOf(System.getProperty("siteId")),
			new NavigationMenu() {
				{
					name = "Foo";
				}
			});

	System.out.println(navigationMenu);
}

このクラスは、わずか3行のコードでRESTサービスを呼び出します。

行（省略形）	説明
NavigationMenuResource.Builder builder = ...	Builderを取得し、NavigationMenuResourceサービスインスタンスを生成します。
NavigationMenuResource navigationMenuResource = builder.authentication(...).build();	基本認証を指定し、NavigationMenuResourceサービスインスタンスを生成します。
NavigationMenu navigationMenu = navigationMenuResource.postSiteNavigationMenu(...);	navigationMenuResource.postSiteNavigationMenuメソッドを呼び出し、投稿するデータを渡します。

プロジェクトには、依存関係としてcom.liferay.headless.delivery.client.jarファイルが含まれていることに注意してください。 すべてのRESTアプリケーションのクライアントJAR依存関係情報は、/o/apiでインストール先のAPIエクスプローラーで確認できます。

注

main メソッドのコメントは、クラスを実行する方法を示しています。

他の例のJavaクラスはこれと類似していますが、異なるNavigationMenuResourceメソッドを呼び出します。

重要

サービスの詳細については、 NavigationMenuResource を参照してください。

以下は、cURLとJavaを使って、他のNavigationMenu RESTサービスを呼び出す例です。

サイトからナビゲーションメニューを取得する

次のcURLまたはJavaコマンドを実行すると、サイトのナビゲーションメニューを一覧表示できます。 上記と同様に、 1234 をサイトIDに置き換えてください。

NavigationMenus_GET_FromSites.sh

コマンド：

./NavigationMenus_GET_FromSites.sh 1234

コード：

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus" \
	--user "[e-mail]:learn"

NavigationMenus_GET_FromSites.java

コマンド：

java -classpath .:* -DsiteId=1234 NavigationMenus_GET_FromSites

コード：

public static void main(String[] args) throws Exception {
	NavigationMenuResource.Builder builder =
		NavigationMenuResource.builder();

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	Page<NavigationMenu> page =
		navigationMenuResource.getSiteNavigationMenusPage(
			Long.valueOf(System.getProperty("siteId")),
			Pagination.of(1, 2));

	System.out.println(page);
}

サイトの NavigationMenu オブジェクトは JSON で表示されます。

ナビゲーションメニューを取得する

以下のcURLまたはJavaコマンドで特定のナビゲーションメニューを取得します。 1234 をナビゲーションメニューのIDに置き換えてください。

ヒント

NavigationMenus_GET_FromSites.[java|sh] を使用して NavigationMenu ID を取得します。

NavigationMenus_GET_ById.sh

コマンド：

./NavigationMenus_GET_ById.sh 1234

コード：

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}" \
	--user "[e-mail]:learn"

NavigationMenus_GET_ById.java

コマンド：

java -classpath .:* -DnavigationMenuId=1234 NavigationMenus_GET_ById

コード：

public static void main(String[] args) throws Exception {
	NavigationMenuResource.Builder builder =
		NavigationMenuResource.builder();

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		navigationMenuResource.getNavigationMenu(
			Long.valueOf(System.getProperty("navigationMenuId"))));
}

NavigationMenu フィールドは JSON に表示されます。

ナビゲーションメニューを配置する

次のcURLおよびJavaコマンドを使用して、既存のナビゲーションメニューを完全に上書きします。 なお、 1234 は、ナビゲーションメニューのIDに置き換えてください。

NavigationMenus_PUT_ById.sh

コマンド：

./NavigationMenus_PUT_ById.sh 1234

コード：

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}" \
	--data-raw '
		{
			"name": "Bar"
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "[e-mail]:learn"

NavigationMenus_PUT_ById.java

コマンド：

java -classpath .:* -DnavigationMenuId=1234 NavigationMenus_PUT_ById

コード：

public static void main(String[] args) throws Exception {
	NavigationMenuResource.Builder builder =
		NavigationMenuResource.builder();

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	NavigationMenu navigationMenu =
		navigationMenuResource.putNavigationMenu(
			Long.valueOf(System.getProperty("navigationMenuId")),
			new NavigationMenu() {
				{
					name = "Bar";
				}
			});

	System.out.println(navigationMenu);
}

ナビゲーションメニューを削除する

以下のcURLおよびJavaコマンドで既存のナビゲーションメニューを削除します。 なお、 1234 は、ナビゲーションメニューのIDに置き換えてください。

NavigationMenus_DELETE_ById.sh

コマンド：

./NavigationMenus_DELETE_ById.sh 1234

コード：

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}" \
	--request "DELETE" \
	--user "[e-mail]:learn"

NavigationMenus_DELETE_ById.java

コマンド：

java -classpath .:* -DnavigationMenuId=1234 NavigationMenus_DELETE_ById

コード：

public static void main(String[] args) throws Exception {
	NavigationMenuResource.Builder builder =
		NavigationMenuResource.builder();

	NavigationMenuResource navigationMenuResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	navigationMenuResource.deleteNavigationMenu(
		Long.valueOf(System.getProperty("navigationMenuId")));
}

API Explorer には、すべての NavigationMenu サービスとスキーマが一覧表示され、各サービスを試すためのインターフェースがあります。

バッチエンジンによるナビゲーションメニュー管理

Liferay DXP 2025.Q3

ナビゲーションメニューAPIは、サイトのナビゲーションメニューおよび関連エンティティをLiferayインスタンス間で移行するためのバッチエクスポートおよびインポートをサポートしています。 関連する 権限を含めたり、作成/変更日やその他の属性に基づいてユーザー定義の フィルタ を適用したり、インポート要求中に 作成者データ がどのように処理されるかを設定できます。

バッチ エンジンの使用方法の詳細については、 バッチ エンジン API を使用したデータのエクスポート および バッチ エンジン API を使用したデータのインポート を参照してください。

ナビゲーションメニューの権限

これらのAPIエンドポイントを使用して、ナビゲーションメニューの権限を管理します。 例の ${1} をサイト ID またはナビゲーション メニュー ID に置き換えてください。

1. 権限付きナビゲーションメニューを作成する

   ナビゲーションメニューエンドポイントに POST リクエストを送信して、作成時にカスタム権限を割り当てます。 指定された役割は、システムに既に存在している必要があります。 指定されたロールが存在しない場合、APIは404エラーを返します。

   パーミッション 配列を省略すると、ナビゲーション メニューはデフォルトのパーミッションで作成されます。

   パーミッション 配列を含めると、Liferay は作成時に指定されたロールとアクションを適用します。

   例:

   curl \
   	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus" \
   	--data-binary '
   		{
   			"name": "Main Menu",
   			"permissions": [
   				{
   					"roleName": "Owner",
   					"actionIds": ["VIEW", "UPDATE"]
   				}
   			]
   		}' \
   	--header "Content-Type: application/json" \
   	--request "POST" \
   	--user "[e-mail]:learn"
   

2. ナビゲーションメニューの権限を取得する

   デフォルトでは、権限はレスポンスに含まれません。 これらを取得するには、クエリに nestedFields=permissions を追加します。

   例:

   curl \
      "http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus?nestedFields=permissions" \
      --user "[e-mail]:learn"
   

3. ナビゲーションメニューの権限を更新する

   PUT リクエストを使用して、既存のナビゲーション メニューの権限を更新します。 ${1} をナビゲーションメニューIDに置き換えてください。

   この操作により、既存のナビゲーションメニューの権限がすべて置き換えられます。 更新後も残るのは、リクエストに含まれていた役割とアクションのみです。

   ヒント

   ナビゲーションメニューIDは、サイトからナビゲーションメニューを取得する際に見つけることができます。

   例:

   curl \
   "http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}/permissions" \
   --data-binary '
      [
         {
            "actionIds": ["VIEW", "UPDATE", "DELETE", "PERMISSIONS"],
            "roleName": "Owner"
         }
      ]' \
   --header "Content-Type: application/json" \
   --request "PUT" \
   --user "[e-mail]:learn"
   

データをフィルタリングする

フィルターを使用すると、取得またはエクスポートするナビゲーションメニューを絞り込むことができます。 フィルターは2つの状況で機能します。

1. getSiteNavigationMenusPage エンドポイントを使用して、フィルタリングされたナビゲーション メニューを取得します。 フィルターパラメータを使用して、必要なメニューのみを取得します。

   curl \
      "http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus?filter=dateCreated%20le%202025-07-18T14%3A25%3A00Z&sort=dateCreated%3Adesc" \
      --header "Content-Type: application/json" \
      --request "GET" \
      --user "[e-mail]:learn"
   

   クエリパラメータの仕組みは以下のとおりです。

   パラメーター	説明
   http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus	ヘッドレス配信 API を使用して、サイト 20126 のナビゲーション メニューを取得するためのエンドポイント。
   filter=dateCreated%20le%202025-07-18T14%3A25%3A00Z	URLエンコードされています。 検索結果を絞り込み、2025年7月18日14時25分（UTC）以前に作成されたメニューのみを含めるようにします。
   sort=dateCreated%3Adesc	URLエンコードされています。 結果を dateCreated の降順 (最新順) で並べ替えます。

   ヒント

   特定のナビゲーション メニューを名前で取得するには、 search= パラメータを追加します。 例えば、

   http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus?filter=dateCreated%20le%202025-07-18T14%3A25%3A00Z&search=Main&sort=dateModified:desc

   これは、名前に Main が含まれるナビゲーション メニューのみを取得します。

2. postSiteNavigationMenusPageExportBatch エンドポイントを使用して、フィルタリングされたナビゲーション メニューをエクスポートします。 エクスポートファイルに含めるメニューを制限するには、同じフィルタ構文を使用します。

   curl \
      "http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus/export-batch?filter=dateCreated%20ge%202025-07-17T00%3A00%3A00Z&search=Main&sort=dateModified%3Adesc" \
      --data-binary '' \
      --header "Content-Type: application/json" \
      --request "POST" \
      --user "[e-mail]:learn"
   

   クエリパラメータの仕組みは以下のとおりです。

   パラメーター	説明
   http://localhost:8080/o/headless-delivery/v1.0/sites/20126/navigation-menus/export-batch	サイト 20126 のナビゲーション メニューのエクスポート バッチを開始するエンドポイント。
   filter=dateCreated%20ge%202025-07-17T00%3A00%3A00Z	URLエンコードされています。 エクスポート対象を、2025年7月17日午前0時（UTC）以降に作成されたメニューに限定します。
   search=Main	フィルターは、名前に「Main」が含まれるメニュー（大文字小文字を区別しない）をエクスポートします。
   sort=dateModified%3Adesc	URLエンコードされています。 注文は、 dateModified の降順（最新が最初）でエクスポートされたメニューです。
   --data-binary ''	フィルタリングとソートはクエリパラメータによって完全に制御されるため、本文は空です。

クリエイターデータの維持

ナビゲーション メニューをインポートする場合、 importCreatorStrategy および creatorStrategy クエリ パラメータを使用して、作成者情報の処理方法を制御できます。

パラメーター	説明
creatorStrategy=INSERT	対象システムに指定された作成者が存在しない場合、新しいユーザーを作成者として追加します。 importCreatorStrategy=KEEP_CREATOR を使用する場合に必要です。
importCreatorStrategy=KEEP_CREATOR	エクスポートされたデータから元の作成者情報を削除します。 creatorStrategy=INSERT も設定されていない限り、作成者が存在しない場合、インポートは失敗します。
importCreatorStrategy=OVERWRITE_CREATOR	元の作成者をインポートしたユーザーに置き換えます。 インポートされたすべてのナビゲーションメニューは、インポートを実行したユーザーに割り当てられます。 省略した場合、デフォルトでこの値が使用されます。

以下に例を示します。

curl \
   "http://localhost:8080/o/headless-batch-engine/v1.0/import-task/com.liferay.headless.delivery.dto.v1_0.NavigationMenu?siteId=20126&creatorStrategy=INSERT&importCreatorStrategy=KEEP_CREATOR" \
   --data-raw '
   [
      {
         "name": "Secondary Menu",
         "externalReferenceCode": "secondary-menu-001",
         "navigationType": "Primary"
      }
   ]' \
   --header "Content-Type: application/json" \
   --request "POST" \
   --user "[e-mail]:learn"