検索APIの基本
Liferay DXP 2025.Q4+/Portal 2026.Q1+で一般提供開始
Liferayの検索ページからコンテンツを検索できますが、/searchAPIエンドポイントを使うこともできます。 Liferay をローカルで実行している場合は、ログインした状態で http://localhost:8080/o/api?endpoint=http://localhost:8080/o/search/v1.0/openapi.json にアクセスして API を調べることができます。
付属のコマンドを使用して、サンプルコンテンツを生成および検索してください。 以下のコマンドは基本認証で動作し、Liferay がローカルで http://localhost:8080 で実行されており、管理者としてメール test@liferay.com とパスワード learn を使用して認証されていることを前提としています。
ブログ記事を生成するには、以下のコマンドを実行してください。
curl \
-H "Content-Type: application/json" \
-X POST \
"http://localhost:8080/o/headless-delivery/v1.0/sites/L_GUEST/blog-postings" \
--data-raw '{"articleBody": "Foo"、 "見出し": "Able"}' \
-u "test@liferay.com:learn"
LiferayバンドルまたはDockerコンテナのデフォルトサイトは、外部参照コード(ERC) L_GUEST を使用します。 インスタンスに L_GUEST ERC を持つサイトがない場合は、上記の呼び出しで、対象とするサイト ID または ERC に置き換えてください。
/search API には、検索結果ページを返すための GET エンドポイントと POST エンドポイントが含まれています。 検索文字列パラメータだけで検索を表現できる場合は、 GET エンドポイントを使用してください。 検索にリクエストボディの機能(例: facetConfigurations などのファセット集計用設定や、検索ブループリントのコンテキスト属性(search.experiences.*)など、リクエストボディの機能が必要な検索を行う場合は、POSTエンドポイントを使用してください。
シンプルなクエリ
キーワード と able に対するシンプルな GET クエリは次のとおりです。
curl \
"http://localhost:8080/o/search/v1.0/search?search=able" \
--user "test@liferay.com:learn"
キーワード と able に対するシンプルな POST クエリは次のとおりです。
curl \
-H "Content-Type: application/json" \
-X POST \
"http://localhost:8080/o/search/v1.0/search?search=able" \
-d "{}" \
-u "test@liferay.com:learn"
どちらの場合も、レスポンスにはブログ記事に関する情報を含む検索結果が返されます。
{
"アイテム" : [ {
"更新日時" : "2023-07-20T17:15:32Z"、
"説明" : "Foo"、
"itemURL" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/35384"、
"score" : 318.95966、
"タイトル" : "可能"
} ],
"最終ページ" : 1,
"ページ" : 1,
"ページサイズ" : 20、
"合計数" : 1
}
新しく作成または変更されたコンテンツは、Liferay がインデックス作成を完了した後、つまり変更がデータベースにコミットされた直後にのみ、 /search の結果に表示されます。 特定のエンティティを生成直後に取得するには、検索するのではなく、IDまたは外部参照コードを使用して、そのエンティティ専用のエンドポイントにリクエストを送信してください。 データ取得: 検索インデックスとデータベースの比較 を参照してください。
埋め込みアイテムを使用したシンプルなクエリ
検索結果だけでなく、返されたエンティティのフィールドをその独自の API スキーマに従って返すには、 nestedFields パラメーターを embedded に設定します。 これはGET検索とPOST検索の両方に適用されます。 例えば、キーワード と able に対するこの POST クエリは、埋め込みアイテムも要求します。
curl \
-H "Content-Type: application/json" \
-X POST \
"http://localhost:8080/o/search/v1.0/search?nestedFields=embedded&search=able" \
-d "{}" \
-u "test@liferay.com:learn"
レスポンスには、ブログ記事に関するより詳細な情報が含まれています。
{
"items" : [ {
"dateModified" : "2023-07-20T17:15:32Z",
"description" : "Foo",
"embedded" : {
"actions": {
"get-rendered-content-by-display-page": {
"メソッド": "GET",
"href": "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/38975/rendered-content-by-display-page/{displayPageKey}"
},
"get": {
"メソッド": "GET",
"href": "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/38975"
},
"replace": {
"メソッド": "PUT",
"href": "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/38975"
},
"update": {
"method": "PATCH",
"href": "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/38975"
},
"delete": {
"method": "DELETE",
"href": "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/38975"
}
},
"alternativeHeadline" : "",
"articleBody" : "Foo",
"creator" : {
"additionalName" : "",
"contentType" : "UserAccount",
"familyName" : "Test",
"givenName" : "Test",
"id" : 20123,
"name" : "Test Test"
},
"customFields" : [ ],
"dateCreated" : "2023-07-20T17:15:32Z",
"dateModified" : "2023-07-20T17:15:32Z",
"datePublished" : "2023-07-20T17:15:00Z",
"description" : "Foo",
"encodingFormat" : "text/html",
"externalReferenceCode" : "f73109ce-8db6-36e3-f2c7-4505c6454ed8",
"friendlyUrlPath" : "able",
"headline" : "Able",
"id" : 35384,
"keywords" : [ ],
"numberOfComments" : 0,
"relatedContents" : [ ],
"renderedContents" : [ ],
"siteId" : 20119,
"taxonomyCategoryBriefs" : [ ]
},
"itemURL" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/35384",
"score" : 318.95966,
"title" : "Able"
} ],
"lastPage" : 1,
"page" : 1,
"pageSize" : 20,
"totalCount" : 1
}
サポートされているパラメータとリクエストボディのプロパティを使用することで、より複雑なリクエストを作成できます。
検索結果フィールド
レスポンスの アイテム 配列内の各結果は、これらのフィールドを持つことができます。 どれが表示されるかは、エンティティとリクエストパラメータによって異なります。
| 項目 | 説明 |
|---|---|
作成日、 更新日 | アイテムの作成および変更のタイムスタンプ(ISO 8601 UTC 形式)(例: 2025-09-20T09:18:45Z)。 |
日付レビュー | 同じ形式でアイテムの予定編集レビュー日 (例: 2026-08-15T14:32:00Z)。レビューワークフローを持つコンテンツタイプでは自動的に入力され、設定されていない場合は null になります。 |
説明、 タイトル | アイテムの説明とタイトルは、エンティティがサポートしている場合、リクエストの Accept-Language ヘッダーに従ってローカライズされます。 |
埋め込み | エンティティ自身のペイロードは、リクエストが nestedFields=embeddedを設定した場合にのみ存在し、エンティティのヘッドレス API スキーマによって形成され、 entryClassName によって変化します。 |
エントリクラス名 | インデックス付きエンティティのクラス名 (例: com.liferay.blogs.model.BlogsEntry) は、 entryClassNames に渡して、後続の検索を絞り込むことができます。 |
アイテムURL | 完全なエンティティを取得するためのヘッドレス REST API URL (例: /o/headless-delivery/v1.0/blog-posting/12345)。 |
スコア | 検索エンジンの関連性スコアを小数値で表したもの(例: 1.42)。スコアが高いほど関連性の高い結果を意味し、しきい値フィルタリングやカスタムランキングに役立ちます。 |
検索パラメータ
クエリパラメータを使用することで、結果をさらに細かく制御できます。
| パラメータ | メモ | 方法 |
|---|---|---|
エントリクラス名 | 検索対象のエントリクラス名をカンマ区切りで指定してください。 デフォルトでは、すべての検索対象タイプが対象となります。 標準で用意されているクラス名と、実行時にそれらを検出する方法については、 検索可能なコンテンツタイプ を参照してください。 | GET POST |
フィールド | fields パラメータは、レスポンス内の各要素において、特定のフィールドのみを列挙するように要求します。 検索が複数のタイプにまたがる場合(entryClassNames が空であるか、複数のクラス名がリストされている場合)、すべてのタイプに共通するフィールドのみが有効になります。 他のフィールドを要求すると、結果項目ごとに空のオブジェクトが返されます。 | GET POST |
ネストされたフィールド | ネストされたデータを取得するために、 に埋め込まれた をサポートします。 | GET POST |
制限フィールド | 各結果から除外するフィールドをカンマ区切りで指定してください。 これは フィールドの逆です。どちらか一方のみを使用してください。両方を使用しないでください。 | GET POST |
フィルター | 複数の分野を横断してフィルタリングします。 サポートされているフィールドは、以下の表に記載されています。 サポートされている演算子は、 eq、 ne、 gt、 ge、 lt、および le です。 複数値コレクションでは、 any() または all() を使用します (例: groupIds/any(g:g eq 20121))。 日付フィールドは、OData Edm.Date 形式 YYYY-MM-DD を使用します。 論理演算子 と、 または、および と を組み合わせて式を結合します。 より高度なフィルタリングオプションを利用するには、検索ブループリント(DXPサブスクリプション)を使用してください。 | GET POST |
ページ | 戻るページを指定してください。 デフォルト値は1です。 | GET POST |
ページサイズ | 1ページあたりの表示件数を指定してください。 デフォルト値は20です。 | GET POST |
範囲 | 検索対象となるサイト、アセットライブラリ、またはスペースのIDまたはERCのリストを指定してください。 同じリクエスト内で ID と ERC を混在させることができます (例: scope=20121,L_GUEST)。 | GET POST |
検索 | キーワードで検索してください。 | GET POST |
選別 | field:asc または field:desc の形式を使用して、昇順または降順でソートします (例: dateModified:desc)。 サポートされているフィールドは、以下の表に記載されています。 デフォルトでは、検索結果は関連性スコアの高い順に並べ替えられます。 | GET POST |
blueprint外部参照コード | 検索要求をカスタマイズするには、 検索ブループリント を指定します。 POSTリクエストでは、代わりに リクエスト属性を使用する必要があります。 | 得る |
空の検索 | 検索 パラメーターに検索キーワードが入力されていない場合に結果を返すには、これをtrueに設定します。 | 得る |
検索ブループリント は、検索ページにソート設定を追加することもできます。 これら2つを併用する場合は、ブループリントで追加されたソートが ソートパラメータとどのように相互作用するかを必ず理解しておいてください。
詳細については、 APIクエリパラメータ を参照してください。
検索可能なコンテンツタイプ
entryClassNames が空の場合、検索は検索可能なすべての型を対象とします。 以下の既成の型とクラス名が利用可能です。
| タイプ | クラス名 |
|---|---|
| 基本文書(CMS) | com.liferay.object.model.ObjectDefinition#Z7P5 |
| 基本的なウェブコンテンツ管理システム(CMS) | com.liferay.object.model.ObjectDefinition#H4T4 |
| ブログ(CMS) | com.liferay.object.model.ObjectDefinition#Y8H4 |
| ブログ記事 | com.liferay.blogs.model.BlogsEntry |
| ブックマークエントリ | com.liferay.bookmarks.model.BookmarksEntry |
| ブックマークフォルダ | com.liferay.bookmarks.model.BookmarksFolder |
| カレンダーイベント | com.liferay.calendar.model.CalendarBooking |
| 商取引製品 | com.liferay.commerce.product.model.CPDefinition |
| 書類 | com.liferay.document.library.kernel.model.DLFileEntry |
| ドキュメントフォルダ | com.liferay.document.library.kernel.model.DLFolder |
| 動的データリストレコード | com.liferay.dynamic.data.lists.model.DDLRecord |
| 外部ビデオ(CMS) | com.liferay.object.model.ObjectDefinition#S1T1 |
| フォーム記録 | com.liferay.dynamic.data.mapping.model.DDMFormInstanceRecord |
| ナレッジベース記事 | com.liferay.knowledge.base.model.KBArticle |
| メッセージボード メッセージ | com.liferay.message.boards.model.MBMessage |
| オブジェクトエントリフォルダ | com.liferay.object.model.ObjectEntryFolder |
| ページ | com.liferay.portal.kernel.model.Layout |
| 共有エントリ | com.liferay.sharing.model.SharingEntry |
| ユーザー | com.liferay.portal.kernel.model.User |
| ウェブコンテンツ記事 | com.liferay.journal.model.JournalArticle |
| ウェブコンテンツフォルダ | com.liferay.journal.model.JournalFolder |
| ウィキペディアページ | com.liferay.wiki.model.WikiPage |
(CMS) とマークされたタイプは、上記のクラス名を使用して、 Liferay CMSを備えたインスタンスでのみ使用できます。
カスタムオブジェクトとカスタム CMS コンテンツ構造は、同じ com.liferay.object.model.ObjectDefinition#[identifier] 形式に従いますが、Liferay はオブジェクト定義を作成する際に各識別子を生成するため、インスタンスの識別子は上記の値とは異なります。 識別子は作成されたインスタンス上では変更されないため、複数の環境にデプロイするコードにハードコーディングするのではなく、実行時に解決するようにしてください。 インスタンス間で安定した値で型を対象とするには、代わりに objectDefinitionExternalReferenceCode でフィルタリングします (たとえば、 filter=objectDefinitionExternalReferenceCode eq 'L_CMS_BASIC_WEB_CONTENT')。 フィルターフィールド を参照してください。
Wiki Page タイプは、Liferay DXP 2024.Q4/Portal GA129 以降 非推奨 となっており、Wiki 非推奨機能フラグ (LPD-35013) は新規インスタンスおよびアップグレードされたインスタンスで無効になっています。 フラグが無効になっている間、Wiki Page は 検索可能なアセット名 および エントリクラス名 が空になる検索結果には表示されません。 com.liferay.wiki.model.WikiPage を明示的に指定したリクエストでも、インデックス付きの wiki ページが返されます。
実行時にインスタンスで使用可能なクラス名を確認するには、 GET /o/search-experiences-rest/v1.0/searchable-asset-names/[language-id] を呼び出します(例: /searchable-asset-names/en-US)。 各エントリにはクラス名とその表示名がペアになっているため、カスタムオブジェクトをその識別子と照合できます。 各検索結果には、 entryClassNameも含まれており、これを entryClassNames に渡して、後続の検索を絞り込むことができます。
フィルターフィールド
ヘッドレスエンティティのレスポンスにこれらのフィールドが含まれている場合、これらのフィールドでフィルタリングやソートを行うことができます。
| APIフィールド | 対応する検索インデックスフィールド | パラメータ |
|---|---|---|
クリエイターID | ユーザーID | フィルター |
フォルダーID | フォルダーID | フィルター |
グループID | グループID | フィルター |
オブジェクト定義ID | オブジェクト定義ID | フィルター |
オブジェクト定義外部参照コード | オブジェクト定義外部参照コード | フィルター |
オブジェクトフォルダー外部参照コード | オブジェクトフォルダー外部参照コード | フィルター |
状態 | 状態 | フィルター |
分類カテゴリID | アセットカテゴリID | フィルター |
作成日 | createDatecreateDate_sortable | フィルター ソート |
日付表示 | displayDatedisplayDate_sortable | フィルター ソート |
有効期限 | expirationDateexpirationDate_sortable | フィルター ソート |
更新日 | 変更済み変更済み_ソート可能 | フィルター ソート |
公開日 | publishDatepublishDate_sortable | フィルター ソート |
日付レビュー | レビュー日レビュー日(ソート可能) | フィルター ソート |
拡大 | 拡大 | フィルター |
キーワード | assetTagNames.lowercase | フィルター ソート |
スコープグループID | スコープグループID | フィルター |
タイトル | localized_title_[locale].keyword_lowercase | フィルター ソート |
この数値は、最新の四半期報告書に基づいています。 フィールドの利用可否はバージョンやエンティティによって異なる場合があります。ご使用の環境のAPIスキーマ内で、特定のフィールドのサポート状況をご確認ください。
- 便宜上、対応する検索インデックスフィールド名が表示されます。 バージョン間で予告なく変更される場合があります。 インデックス付きフィールドの詳細については、 インデックス付きフィールドの探索 を参照してください。
- ヘッドレス API フィールド
キーワードは、エンティティの タグ名 を参照します。
ステータスによるフィルタリング
DXP 2025.Q3+
デフォルトでは、検索時に承認済みのアイテムのみが返されます(つまり、ステータスが 0 のアイテム)。 ステータスフィールドでフィルタリングすることで、他のワークフローステータスを持つアイテムを取得できます。 例えば、承認済みアイテムと保留中アイテムの両方を返すフィルター値は、 status eq 0 or status eq 1 です。 式を フィルター パラメーターに渡し、GET リクエストでは URL エンコードします。
curl \
"http://localhost:8080/o/search/v1.0/search?filter=status%20eq%200%20or%20status%20eq%201&search=able" \
--user "test@liferay.com:learn"
以下のステータス値が利用可能です。
| 価値 | 状態 |
|---|---|
-1 | どれでも |
0 | 承認された |
1 | 保留中 |
2 | 下書き |
3 | 期限切れ |
4 | 拒否されました |
5 | 非アクティブ |
6 | 不完全 |
7 | 予定 |
8 | ゴミ箱 |
9 | 空の |
ウェブコンテンツ記事をステータスでフィルタリングすることはできません。 検索によって返されるのは ヘッド バージョン (最新の承認済みコンテンツ) のみとなるようにする組み込みのフィルターがあります。 ウェブコンテンツの結果を制限するには、 スコープ パラメーターを使用するか、 groupIds でフィルタリングしてください。デフォルトでは、承認済みのアイテムのみが返されます。
検索リクエスト本文
GET検索ではリクエストボディは含まれません。 POST検索では、空のリクエストも許可されています(例:リクエストボディとして {} を指定します)が、レスポンスに影響を与えるために使用できるプロパティが2つあります。
| 財産 | 説明 |
|---|---|
属性 | 利用可能な検索コンテキスト属性を設定して、検索ブループリントを構成するか、空の検索を有効にします。 詳細については、 利用可能な検索リクエスト属性 を参照してください。 |
ファセット構成 | レスポンスにファセットを含めるように、ファセット設定を行います。 リクエストにファセット構成を追加する を参照してください。 |
検索リクエストに属性を追加する
ブループリントを使用して検索するには、次のリクエストボディ構文を使用します。
{
"属性": {
"search.experiences.blueprint.external.reference.code": ""
}
}
カスタム検索リクエスト属性
API リクエストにカスタム属性を追加し、 検索ブループリント でその値を使用できます。 カスタム属性を使用すると、検索リクエストは動的なコンテキストデータを受け取り、それをブループリントに渡すことができます。 ブループリントでは、値でフィルタリングしたり、クエリの設定に使用したり、 条件 に追加したりすることができます。 これにより、コンテキストデータを使用してパーソナライズされた検索体験を作成することが可能になります。
カスタム属性の接頭辞として search.experiences を付けます。 この例では、 freshnessInteger とその値を検索リクエストに追加します。
{
"属性": {
"search.experiences.freshnessInteger": 30
}
}
属性をブループリント内の パラメーターとして宣言し、その型を指定します。
{
"パラメータ": {
"search.experiences.freshnessInteger": {
"タイプ": "Integer"
}
}
}
要素 内で値 を使用します。 例えば、 範囲 クエリと createDate フィールドを使用して、過去 30 日間に公開されたコンテンツをクエリします。
"クエリ": {
"範囲": {
"作成日": {
"gte": "現在-"${search.experiences.freshnessInteger}d/d"、
"lte": "now/d"
}
}
}
利用可能な検索リクエスト属性
リクエストに以下の属性を設定できます:
| 財産 | 説明 |
|---|---|
検索.空.検索 | リクエストから検索パラメータ が省略された場合でも結果を返すには、これを true に設定します。 |
DXPのみsearch.experiences.blueprint.external.reference.code | (推奨)検索クエリと構成を制御するために、 検索ブループリント を設定します。 |
DXPのみsearch.experiences.blueprint.id | 検索クエリと構成を制御するには、 検索ブループリント を設定します。 |
DXPのみsearch.experiences.ip.address | 自動的に設定されます。 異なる場所をシミュレートするために、地理位置情報 が設定されたブループリント をテストする場合にのみこれを使用してください。 |
DXPのみsearch.experiences.scope.group.id | ブループリントで、これを必要とする 要素 を使用する場合は、これを設定します。検索を現在のサイトに限定する、ユーザーセグメントのカテゴリ内のコンテンツをブーストする、またはステージング対応です。 |
DXPのみsearch.experiences.* | カスタム属性を使用することで、ブループリントを基盤とするヘッドレス検索リクエストに動的なデータを渡すことができます。 これらの属性の前に search.experiences. を付けます。 そして、それらをブループリントの パラメータ設定で宣言します。 |
リクエストにファセット設定を追加する
ファセット設定を使用して検索するには、次のリクエストボディ構文を使用します。
{
"facetConfigurations": [
{
"aggregationName": "",
"attributes": {},
"frequencyThreshold": "",
"maxTerms": "",
"name": ""、
"値": []
}
]
}
ファセット構成には、いくつかのプロパティがあります。
| 財産 | 説明 |
|---|---|
集計名 | 集計に固有の名前を選択してください。 これは、同じタイプのインスタンス(つまり、同じ 名前 プロパティを持つインスタンス)を区別するために必要です。 |
属性 | 一部のファセットには追加の属性が必要です。field: カスタムファセット、日付範囲ファセット、およびネストされたファセットでは、集計の対象となるフィールドを設定するために、「field」という名前の文字列属性が必要です。フォーマット および 範囲: 日付範囲 ファセットには、日付フォーマットを指定するための フォーマット 文字列も必要です (例: yyyyMMddHHmmss) と 範囲 オブジェクト配列を使用して範囲を指定します。filterField、 filterValue、および パス: ネストされた ファセットには、 filterField 文字列、 filterValue 文字列、および path 文字列が必要です。vocabularyIds: 語彙 ファセットには、 vocabularyIds の文字列配列が必要です。 GET /o/headless-admin-taxonomy/v1.0/sites/{siteId}/taxonomy-vocabularies を使用して語彙 ID を検出します。 |
周波数しきい値 | ファセット用語リストに用語が表示されるために必要な最小頻度を設定します。 デフォルト値は1です。 |
最大期間 | ファセットに一致する用語がいくつ見つかったかに関わらず、表示するファセット用語の最大数を設定します。 デフォルト値は10です。 |
名前 | ファセットの種類を設定します:カテゴリカスタム日付範囲フォルダネストされたサイトタグタイプ語彙ユーザー |
値 | 値を選択して結果を後処理で絞り込みます。 これは、ファセットウィジェットでファセット用語をクリックするのと似ています。 |
カスタム、 日付範囲、または ネストされた ファセット構成で必須属性が省略されている場合、リクエストは成功しますが、レスポンスにはそのファセットの集計は含まれません。 認識されない 名前 値を持つファセット構成にも同じことが当てはまります。
カスタム ファセットは、トップレベルのフィールドを認識します。 オブジェクトと Web コンテンツ構造フィールドはネストされたフィールドとしてインデックス化されるため、これらのエンティティには ネストされた ファセットを選択する必要があります。
例えば、 日付範囲 ファセットの 範囲 属性は次のようになります。
{
"範囲": [
{
"ラベル": "範囲-1"、
"範囲": "[20220411085757 TO 20230413075757]"
},
{
"ラベル": "範囲-2",
"範囲": "[20230409085757 TO 20230413075757]"
}
]
}
レスポンスにおける集計と検索ファセット
GET検索ではファセットは返されません。 POST検索の場合、APIレスポンスで集計と 検索ファセット を確認できます。 集計結果を見るには、
リクエストに ファセット構成 を追加すると、検索ファセットが返されます。 例えば、このリクエストボディはタグファセットを要求しています。
{
"facetConfigurations": [
{
"name": "tag"
}
]
}
レスポンスでは、返された検索ファセットは次のようになります。
"searchFacets": {
"tag": [
{
"displayName": "business",
"term": "business",
"frequency": 26
},
{
"displayName": "fun"、
"用語": "楽しさ"、
"頻度": 1
}
]
}
searchFacets マップは、各ファセット構成の aggregationName をキーとしています。 キーを設定しない場合、キーはデフォルトでファセットの 名前になります。そのため、この例のキーは タグ になります。 マップは、リクエストに facetConfigurations が含まれている場合にのみレスポンスに表示されます。
検索APIへのゲストアクセスを有効にする
ゲストが API にアクセスできるようにするには、 次のように新しいサービス アクセス ポリシー を作成します。
| 分野 | エントリ |
|---|---|
| 名前 | 検索 |
| 有効 | 確認済み |
| デフォルト | 確認済み |
| タイトル | 検索APIへの一般アクセス |
| サービスクラス名 | com.liferay.portal.search.rest.internal.resource.v1_0.SearchResultResourceImpl |
| メソッド名 | [postSearchPage OR getSearchPage] |