フィードバックを送信
Content Management APIs
ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、 こちら までご連絡ください。

フラグメントAPIの基本

ベータ版機能

Liferay の headless-admin-fragment モジュールは、 サイト (ページとコンテンツをグループ化するための Liferay の単位) 内のフラグメント セットとフラグメントに対する REST サービスを提供します。 これらのサービスを利用すると、フラグメントセットとその中に含まれるフラグメントを作成、取得、更新、削除できます。 ここでは、cURLコマンドを使用してこれらのサービスを呼び出します。

重要

このAPIは、ベータ版機能フラグ「フラグメント管理API」（LPD-39244）を有効にすることで利用できます。 これはベータ版の機能であるため、これらのエンドポイントはまだ開発段階であり、変更される可能性があります。 有効にするには、 ベータ機能フラグ を参照してください。

フラグメントセットは、関連するフラグメントをグループ化したものです。 フラグメントとは、フラグメントセットに属する、再利用可能な単一のページ要素のことです。 フラグメントは常にフラグメントセットに属するため、まずフラグメントセットを作成する必要があります。

フラグメントセットを追加する

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

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

http://localhost:8080 に、メールアドレス test@liferay.com とパスワード test を使用して Liferay にサインインします。 プロンプトが表示されたら、パスワードを learn に変更してください。

次に、以下の手順に従ってください。

  1. フラグメント管理 API ベータ機能フラグを有効にします。 グローバルメニュー (Global Menu) を開き、 コントロールパネル → インスタンス設定 に移動します。 プラットフォームの下にある 機能フラグ をクリックし、次に ベータをクリックして、 フラグメント管理 API をオンに切り替えます。 このフラグが有効になるまで、以下のサービス呼び出しは 404 Not Found を返します。 機能フラグを有効にするには、Liferayインスタンスへの管理者権限が必要です。

  2. フラグメント API の基本 をダウンロードして解凍します。

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

    unzip liferay-s2v4.zip

  3. サイトの外部参照コード (ERC) を見つけてください。 Fragment および Fragment Set エンドポイントは、ERC によってサイトを指定します。 以下の各サービス呼び出しでこの値を使用してください。

  4. curl フォルダーに移動し、サイトの ERC をパラメーターとして使用して FragmentSets_POST_ToSites.sh を実行します。 これにより、指定されたサイトに新しいフラグメントセットが作成されます。

    cd liferay-s2v4/curl

    ./FragmentSets_POST_ToSites.sh [site-erc]

    ターミナルには、新しく作成されたフラグメントセットの完全なスキーマが表示されます。

    {
  "作成者" : { ... }、
  "作成日" : "2026-07-01T14:00:00Z"、
  "更新日" : "2026-07-01T14:00:00Z"、
  "説明" : "このフラグメント セットは、ヘッドレス API によって作成されました。"、
  "externalReferenceCode" : "able-fragment-set"、
  "key" : "able-fragment-set"、
  "マーケットプレイス" : false,
  "名前" : "Able フラグメント セット"
}

  5. フラグメントセットのERCをコピーします。 このチュートリアルの残りの部分では、それを使用します。

重要

提供されているコードは、デモンストレーション目的で基本認証を使用しています。 本番環境では、 OAuth2 を使用してユーザーを認証する必要があります。

cURLコマンドを調べてみましょう

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

curl \
	"http://localhost:8080/o/headless-admin-fragment/v1.0/sites/${1}/fragment-sets" \
	--data-raw '
		{
			"description": "このフラグメント セットは、ヘッドレス API によって作成されました。"、
			"キー": "able-fragment-set"、
			"名前": "Able Fragment Set"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

主な論点は

口論説明
--header "Content-Type: application/json"リクエストボディのフォーマットとしてJSONを宣言します。
--リクエスト "POST"指定されたエンドポイントで起動するHTTPメソッド
"http://localhost:8080/o/headless-admin-fragment/v1.0/sites/${1}/fragment-sets"指定されたサイトにフラグメントセットを作成するためのRESTサービスエンドポイント
--data-raw '{...}'フラグメントセットのプロパティを含むJSONボディ
--user "test@liferay.com:learn"基本的な認証情報

--data-raw の JSON ボディには、次のパラメータが含まれます。

パラメータ説明
説明フラグメントセットのテキスト説明
鍵フラグメントセットの一意のキー（内部的に使用）
名前フラグメントセットの表示名（必須）
重要

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

フラグメントセットを入手する

以下のcURLコマンドを使用して、特定のフラグメントセットを取得します。 [site-erc] および [fragment-set-erc] を、サイトおよびフラグメント セットの ERC に置き換えてください。

FragmentSets_GET_ByExternalReferenceCode.sh

コマンド：

./FragmentSets_GET_ByExternalReferenceCode.sh [site-erc] [fragment-set-erc]

コード：

curl \
	"http://localhost:8080/o/headless-admin-fragment/v1.0/sites/${1}/fragment-sets/${2}" \
	--user "test@liferay.com:learn"

応答は前の手順で示したスキーマと一致しており、作成した詳細情報を持つフラグメントセットが存在することが確認されました。

フラグメントを追加する

フラグメントセット内にフラグメントを作成するには、まずフラグメントセットが存在している必要があります。 フラグメントセットは既にURLによって識別されているため、リクエストボディにはフラグメントセットへの参照は含まれません。

重要

すべてのフラグメントの作成または更新には、リクエスト本文に 型 の BasicFragment または FormFragment が必要であり、フラグメントの 型 は作成後に固定されます。 基本フラグメントとフォームフラグメント を参照してください。

  1. サイトの ERC とフラグメント セットの ERC をパラメータとして使用して、 Fragments_POST_ToFragmentSets.sh を実行します。 これにより、指定されたフラグメントセット内に新しいフラグメントが作成されます。 このスクリプトは、キー charlie-fragment と名前 "Charlie Fragment" を使用します。

    ./Fragments_POST_ToFragmentSets.sh [site-erc] [fragment-set-erc]

    ターミナルには、新しく作成されたフラグメントの完全なスキーマが表示されます。

    {
  "キャッシュ可能" : ...,
  "作成者" : { ... }、
  "作成日" : "2026-07-01T14:05:00Z"、
  "dateModified" : "2026-07-01T14:05:00Z",
  "externalReferenceCode" : "charlie-fragment",
  "fragmentVersions" : [
    {
      "configuration" : "{\"fieldSets\":[]}",
      "css" : ""、
      "html" : "<div>Charlie Fragment</div>"、
      "js" : ""、
      "ステータス" : "承認済み"
    }
  ]、
  "アイコン" : ""、
  "キー" : "チャーリーフラグメント"、
  "マーケットプレイス" : false、
  "名前" : "Charlie Fragment"、
  "readOnly" : false、
  "タイプ" : "BasicFragment"
}
    注記

    レスポンスには thumbnailURLReference が含まれますが、これは nestedFields クエリ パラメータを使用してリクエストした場合のみです。たとえば、 http://localhost:8080/o/headless-admin-fragment/v1.0/sites/[site-erc]/fragments/[fragment-erc]?nestedFields=thumbnailURLReference の場合です。

  2. フラグメントのERCをコピーします。 フラグメントサービス で説明されているフラグメントサービスで使用します。

cURLコマンドを調べてみましょう

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

curl \
	"http://localhost:8080/o/headless-admin-fragment/v1.0/sites/${1}/fragment-sets/${2}/fragments" \
	--data-raw '
		{
			"fragmentVersions": [
				{
					"設定": "{\"fieldSets\":[]}"、
					"css": ""、
					"html": "<div>Charlie Fragment</div>"、
					"js": ""、
					"ステータス": "承認済み"
				}
			]、
			"キー": "チャーリーフラグメント"、
			"名前": "Charlie Fragment"、
			"タイプ": "BasicFragment"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

このスクリプトは FragmentSets_POST_ToSites.shと同じ引数パターンに従いますが、 "http://localhost:8080/o/headless-admin-fragment/v1.0/sites/${1}/fragment-sets/${2}/fragments" に投稿します。 サイトのERCとフラグメントセットのERCは、新しいフラグメントがどこに追加されたかを識別します。 JSON本文には以下のパラメータが含まれます。

パラメータ説明
フラグメントバージョンFragmentVersion のステータスが または で 承認済み または ドラフト であることが少なくとも 1 つ必要です。 その 構成 は、ネストされた JSON オブジェクトではなく、シリアル化された JSON を含む文字列なので、引用符をエスケープします: "構成": "{\"fieldSets\":[]}"。 承認済みバージョンの 構成 が JSON オブジェクトとして解析されると、Liferay はそれをフラグメント構成スキーマに対して検証します。フラグメント構成スキーマで認識される唯一のルート プロパティは fieldSets です。 フラグメントに構成フィールドがない場合は、 {"fieldSets":[]} を使用してください。
鍵グループ内のフラグメント固有のキー。 Liferay は、 という名前を省略すると から 1 つを生成します。
名前フラグメントの表示名（必須）
タイプBasicFragment または FormFragment (必須)； BasicおよびFormFragment を参照

フラグメントの html、 css、 js、および 設定 の値は、その fragmentVersions エントリにあります。 フラグメントには、ドラフト版のみ、承認済み版のみ、または両方を同時に格納できます。 アップデートには少なくとも1つのバージョンを含める必要があり、公開済みのフラグメントの承認済みバージョンを削除することはできません。そのため、すべてのアップデートで既存のバージョンを再送信してください。

フラグメントサービス

残りの フラグメント サンプル ファイルは、フラグメント セット サービスと同様に機能し、サイトの ERC とフラグメント自身の ERC によってフラグメントを識別します。 liferay-s2v4/curl フォルダーからそれぞれ実行し、 [site-erc] をサイトの ERC に、 [fragment-erc] を前のセクションでコピーした Fragment ERC に置き換えます。

./Fragments_GET_ByExternalReferenceCode.sh [site-erc] [fragment-erc]

./Fragments_PUT_ByExternalReferenceCode.sh [site-erc] [fragment-erc]

./Fragments_DELETE_ByExternalReferenceCode.sh [site-erc] [fragment-erc]

これらの呼び出しでは、フラグメントセットのERCではなく、フラグメントのERCが2番目の位置に配置されます。

ファイル説明
Fragments_GET_ByExternalReferenceCode.sh指定されたフラグメントの詳細を返します。
Fragments_PUT_ByExternalReferenceCode.sh指定されたフラグメントの詳細を更新します。 名前を「Dog Fragment」に変更し、既存の fragmentVersions エントリは変更せずに再送信するため、フラグメントは元の「Charlie Fragment」コンテンツを保持し、名前のみが変更されます。リクエストには少なくとも 1 つのバージョンを含める必要があり、そうでない場合は更新が失敗します。
Fragments_DELETE_ByExternalReferenceCode.sh指定されたフラグメントを削除します。 削除が成功すると、空の 204 No Content レスポンスが返されます。

APIには関連する機能がいくつか存在しますが、実行可能なサンプルプロジェクトには含まれていません。

  • サイト内のすべてのフラグメント セットまたはフラグメントを一覧表示します (GET /sites/{siteExternalReferenceCode}/fragment-sets および GET /sites/{siteExternalReferenceCode}/fragments)。
  • フラグメント セットの URL の下にネストするのではなく、リクエスト ボディでフラグメント セットを指定して、サイトの直下にフラグメントを作成します (POST /sites/{siteExternalReferenceCode}/fragments)。
  • フィルタ クエリ パラメータを使用して、サイト レベルのフラグメント リストを絞り込みます。 OData フィルタ構文 を使用します。

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

フラグメントセットを更新する

以下のcURLコマンドを使用して、既存のフラグメントセットを更新します。 [site-erc] および [fragment-set-erc] を、サイトおよびフラグメント セットの ERC に置き換えてください。

FragmentSets_PUT_ByExternalReferenceCode.sh

コマンド：

./FragmentSets_PUT_ByExternalReferenceCode.sh [site-erc] [fragment-set-erc]

コード：

curl \
	"http://localhost:8080/o/headless-admin-fragment/v1.0/sites/${1}/fragment-sets/${2}" \
	--data-raw '
		{
			"description": "このフラグメントセットが更新されましたヘッドレス API による。"、
			"name": "Baker Fragment Set"
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

このスクリプトはフラグメントセットの名前を「Baker Fragment Set」に変更します。

{
...
  "名前" : "ベイカーフラグメントセット"、
...
}
重要

フラグメント セットが存在する場合、 dateModified、 description、および name のみが尊重されます。 dateCreated、 externalReferenceCode、 key、および marketplace に対して送信された値はすべて無視されます。 渡された ERC に一致するフラグメント セットがない場合、このリクエストは代わりに キー、 マーケットプレイス、および dateCreated を適用してフラグメント セットを作成します。 ERCを注意深く確認してください。タイプミスがあると、意図したフラグメントセットが更新されるのではなく、新しいフラグメントセットが作成されてしまう可能性があります。 フラグメントセットの外部参照コードは、常にURLから取得されます。

フラグメントセットを削除する

以下のcURLコマンドを使用して、既存のフラグメントセットを削除します。 [site-erc] および [fragment-set-erc] を、サイトおよびフラグメント セットの ERC に置き換えてください。

FragmentSets_DELETE_ByExternalReferenceCode.sh

コマンド：

./FragmentSets_DELETE_ByExternalReferenceCode.sh [site-erc] [fragment-set-erc]

コード：

curl \
	"http://localhost:8080/o/headless-admin-fragment/v1.0/sites/${1}/fragment-sets/${2}" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

削除が成功すると、空の 204 No Content レスポンスが返されます。

基本断片と形式断片

フラグメントには 型 が必要です。 FragmentResource サービスは、2 つのフラグメントサブタイプを区別します。

  • BasicFragment: JSON で設定されたフラグメント。 このチュートリアルのサンプルcURLスクリプトは、このタイプのスクリプトを作成します。
  • FormFragment: フォームフラグメントが収集する入力フィールドタイプをリストする fieldTypes 配列を追加します。 使用可能なフィールドタイプは、 ブール値、 CAPTCHA、 日付、 日時、 メールアドレス、 ファイルです。 FormButton、 FriendlyURL、 HTML、 LocalizationSelect、 LongText、 Multiselect、 番号、 電話番号、 関係、 選択、 ステッパー、および テキスト。
重要

すべてのフラグメントの作成または更新リクエストは、 タイプ を BasicFragment または FormFragment に設定します。 フラグメントの 型 は作成時に固定されるため、フラグメントを2つのサブタイプ間で移動するには、フラグメントを削除して再度作成する必要があります。

この cURL の例は、 FormFragment の作成ペイロードを示しています。

curl \
   "http://localhost:8080/o/headless-admin-fragment/v1.0/sites/[site-erc]/fragment-sets/[fragment-set-erc]/fragments" \
   --data-raw '
      {
         "key": "contact-form-fragment"、
         "名前": "お問い合わせフォームフラグメント"、
         "タイプ": "FormFragment"、
         "fieldTypes": ["Text", "Email", "LongText"],
         "fragmentVersions": [
            {
               "設定": "{\"fieldSets\":[]}"、
               "css": ""、
               "html": "<form>...</form>",
               "js": "",
               "ステータス": "承認済み"
            }
         ]
      }' \
   --header "Content-Type: application/json" \
   --request "POST" \
   --user "test@liferay.com:learn"

フラグメントセットの追加機能

このチュートリアルで紹介するCRUDフローと並行して、いくつかの関連機能も存在します。

  • Liferay Marketplace からインストールされたフラグメントは、 marketplace: true のリストに表示されます。 それらの html、 css、 js、および 設定 は読み取り時に保留されるため、エクスポートとインポートは作成したフラグメントをカバーします。
  • デフォルト（システム）フラグメントは、一覧表示およびエクスポート／インポートから完全に除外されます。
  • フラグメント構成 (フラグメントをグループ化して単一の再利用可能な単位として保存したもの) および非推奨の Fragments Toolkit を使用して構築されたフラグメントは、この API の対象外です。
  • フラグメント セットに属するリソース ファイルとフォルダーは、ネストされたフォルダーをサポートする ドキュメントとメディア をモデルとしており、このチュートリアルの実行可能な例ではカバーされていない関連機能です。
  • Liferayのバッチエンジンを使用すると、複数の環境間でフラグメントセットを一括でエクスポートおよびインポートできます。 バッチエンジンAPIの基本: データのインポート および バッチエンジンAPIの基本: データのエクスポート を参照してください。

エラー処理

Fragment サービスと Fragment Set サービスを呼び出すと、問題を説明するエラーメッセージが誤って返されます。

状況エラーメッセージ
フラグメント管理 API ベータ機能フラグを有効にする前に、これらのエンドポイントのいずれかを呼び出すと、リクエストは 404 Not Found を返します。
リクエストボディでフラグメントセットを指定せずに、 POST /sites/{siteExternalReferenceCode}/fragments を使用してフラグメントを作成する新しいフラグメントを作成するには、フラグメントセットの外部参照コードが必要です。
存在しないフラグメントセット ERC を使用して、 /sites/{siteExternalReferenceCode}/fragments のフラグメントを作成または更新しています。外部参照コード {0} を持つフラグメントセットは見つかりませんでした。
リクエストボディに少なくとも1つの FragmentVersion がない状態でフラグメントを更新する少なくとも1つのフラグメントエントリバージョンが必要です。
公開済みのフラグメントの FragmentVersion ステータスを Draft に戻します。フラグメントエントリの非公開はサポートされていません。
フラグメントを、作成時に使用されたタイプと異なるタイプ で更新するフラグメントタイプは変更できません。
Capability:
Content Management System
Resource Type:
Official Documentation
Feature:
API Development
Fragments
Deployment Approach:
Liferay PaaS
Liferay SaaS
Liferay Self-Hosted