検索APIの基本
Liferay DXP 2025.Q4+/Portal 2026.Q1+で一般提供開始
Liferay 検索ページから コンテンツを検索 できますが、 /search API エンドポイントを使用することもできます。 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", "headline": "Able"}' \
-u "test@liferay.com:learn"
LiferayバンドルまたはDockerコンテナ内のデフォルトのサイトでは、外部参照コード（ERC） L_GUESTが使用されます。 インスタンスに L_GUEST ERC を持つサイトがない場合は、上記の呼び出しでそれをターゲットとするサイト ID または ERC に置き換えます。
/search API には、検索結果ページを返す GET および 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"
どちらの場合も、応答にはブログ投稿に関する情報を含む検索結果が返されます。
{
"items" : [ {
"dateModified" : "2023-07-20T17:15:32Z",
"description" : "Foo",
"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
}
埋め込みアイテムを使用したシンプルなクエリ
検索結果だけでなく、返されたエンティティのフィールドを独自の API スキーマに従って返すには、 nestedField パラメータを 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": {
"method": "GET",
"href": "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/38975/rendered-content-by-display-page/{displayPageKey}"
},
"get": {
"method": "GET",
"href": "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/38975"
},
"replace": {
"method": "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
}
サポートされているパラメータとリクエスト本体のプロパティを使用して、より複雑なリクエストを構築できます。
検索パラメータ
クエリパラメータを使用して、結果をさらに制御できます。
| パラメーター | メモ | メソッド |
|---|---|---|
entryClassNames | 検索対象となる entryClassNames のコンマ区切りリスト。 デフォルトでは、検索可能なすべてのタイプになります。 | GET POST |
fields | fields パラメータは、レスポンス内の各要素で特定のフィールドのみを列挙するよう要求します。 | GET POST |
nestedFields | ネストされたデータを取得するための 埋め込み をサポートします。 | GET POST |
restrictFields | 指定されたフィールドを返されないよう除外します。 | GET POST |
filter | さまざまなフィールドにわたってフィルターします。 サポートされているフィールドは以下の表に表示されます。 より強力なフィルタリング オプションについては、検索ブループリント (DXP サブスクリプション) を使用してください。 | GET POST |
page | 返すページを指定します。 | GET POST |
pageSize | ページあたりに必要なアイテム数を指定します。 | GET POST |
scope | 検索するサイトのリスト（ID または ERC 別）を指定します。 同じリクエスト内で ID と ERC を混在させることができます。 | GET POST |
search | キーワードで検索します。 | GET POST |
sort | 昇順または降順で並べ替えます。 サポートされているフィールドは以下の表に表示されます。 | GET POST |
blueprintExternalReferenceCode | 検索リクエストをカスタマイズするには、 検索ブループリント を指定します。 POST リクエストでは代わりに リクエスト属性を使用する必要があります。 | GET |
emptySearch | 検索 パラメータに検索キーワードが入力されていない場合に結果を返すには、これを true に設定します。 | GET |
検索ブループリント では、検索ページに並べ替え構成を追加することもできます。 両方を使用する予定の場合は、ブループリントによって追加されたこれらの並べ替え が並べ替え パラメーターとどのように相互作用するかを必ず理解してください
詳細については、 API クエリ パラメータ を参照してください。
フィルターフィールド
ヘッドレス エンティティの応答にこれらが存在する場合は、次のフィールドでフィルタリングしたり並べ替えたりすることができます。
APIフィールド 対応する検索インデックスフィールド パラメーター 作成者ID userId 絞り込み フォルダID フォルダID 絞り込み グループID groupId 絞り込み objectDefinitionId objectDefinitionId 絞り込み オブジェクトフォルダー外部参照コード オブジェクトフォルダー外部参照コード 絞り込み status status 絞り込み 分類カテゴリID 資産カテゴリID 絞り込み 作成日 createDate
createDate_sortable フィルター
並べ替え 日付表示 表示日付
表示日付_ソート可能 フィルター
並べ替え 有効期限 有効期限
有効期限ソート可能 フィルター
並べ替え 日付変更 変更済み
修正済みソート可能 フィルター
並べ替え 公開日 公開日
公開日_ソート可能 フィルター
並べ替え 日付レビュー レビュー日
レビュー日_ソート可能 フィルター
並べ替え キーワード 資産タグ名.小文字 フィルター
並べ替え title localized_title_[ロケール].keyword_lowercase フィルター
並べ替え
重要
- 便宜上、対応する検索インデックス フィールド名が表示されます。 バージョン間で予告なく変更されることがあります。 インデックス付きフィールドの詳細については、「 インデックス付きフィールドの調査 」を参照してください。
- すべてのフィールドがすべてのヘッドレス エンティティに存在するわけではありません。 エンティティのスキーマを検査してそのフィールドを確認します。
- ヘッドレス API フィールド
キーワード は、エンティティの タグ名を参照します。
ステータスによるフィルタリング
DXP 2025.Q3以降
デフォルトでは、検索時に承認されたアイテムのみが返されます (つまり、ステータスが 0のアイテム)。 他のワークフロー ステータスのアイテムは、ステータス フィールドでフィルター処理することによって返されます。 たとえば、承認済みアイテムと保留中のアイテムの両方を返すフィルター値は、 status eq 0 または status eq 1です。
Web コンテンツの記事をステータス別にフィルタリングすることはできません。 検索によってコンテンツの ヘッド バージョンのみが返されるようにする組み込みフィルターがあります。 つまり、検索できるのは最新の承認済みコンテンツのみとなります。
検索リクエスト本文
GET 検索にはリクエスト本文は含まれません。 POST 検索では、空のリクエストが許可されます (例: リクエスト本体として {} を指定します)。ただし、レスポンスに影響を与えるために使用できるプロパティが 2 つあります。
プロパティ 説明 attributes利用可能な検索コンテキスト属性を設定して、検索ブループリントを構成するか、空の検索を有効にします。 詳細については、 「利用可能な検索リクエスト属性」を参照してください。 facetConfiguration応答でファセットを返すようにファセット構成を設定します。 リクエストへのファセット構成の追加を参照してください。
検索リクエストに属性を追加する
ブループリントを使用して検索するには、次のリクエスト本文構文を使用します。
{
"attributes": {
"search.experiences.blueprint.external.reference.code": ""
}
}
カスタム検索リクエスト属性
API リクエストにカスタム属性を追加し、その値を 検索ブループリントで使用することができます。 カスタム属性を使用すると、検索リクエストは動的なコンテキスト データを受信し、それをブループリントに渡すことができます。 ブループリントでは、値でフィルタリングしたり、値を使用してクエリを構成したり、値を 条件に追加したりすることができます。 これにより、コンテキスト データを使用してパーソナライズされた検索エクスペリエンスを作成できます。
カスタム属性の前に search.experiencesを付けます。 この例では、 freshnessInteger とその値を検索リクエストに追加します。
{
"attributes": {
"search.experiences.freshnessInteger": 30
}
}
ブループリントで、属性を パラメータとして宣言し、その型を次のように指定します。
{
"parameters": {
"search.experiences.freshnessInteger": {
"type": "Integer"
}
}
}
要素に値 を使用します。 たとえば、 range クエリと createDate フィールドを使用して、過去 30 日間に公開されたコンテンツをクエリします。
"query": {
"range": {
"createDate": {
"gte": "now-"${search.experiences.freshnessInteger}d/d",
"lte": "now/d"
}
}
}
利用可能な検索リクエスト属性
リクエストには、次の 属性 を設定できます。
プロパティ 説明 search.empty.searchリクエストから search パラメータが省略されている場合でも結果を返すには、これを 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": "",
"values": []
}
]
}
ファセット構成にはいくつかのプロパティがあります。
プロパティ 説明 aggregationName集計に一意の名前を選択します。 これは、同じタイプのインスタンス (つまり、同じ 名前 プロパティを持つインスタンス) を区別するために必要です。 attributes一部のファセットには追加の属性が必要です。
フィールド: カスタム、 日付範囲、および ネストされた ファセットには、結果を集計するフィールドを設定するために、 フィールド という文字列属性が必要です。
形式 および 範囲: 日付範囲 ファセットには、日付形式を指定するための 形式 文字列 (例: yyyyMMddHHmmss) と、範囲を提供するための 範囲 オブジェクト配列も必要です。
フィルターフィールド、 フィルター値、および パス: ネストされた ファセットには、 フィルターフィールド 文字列、 フィルター値 文字列、および パス 文字列。
vocabularyIds: vocabulary ファセットには、 vocabularyIdsの文字列配列が必要です。 frequencyThresholdファセット用語のリストに用語が表示されるために必要な最小頻度を設定します。 maxTermsファセットに一致する用語がいくつ見つかったかに関係なく、表示するファセット用語の最大数を設定します。 nameファセットのタイプを設定します:
カテゴリ
カスタム
日付範囲
フォルダー
ネスト
サイト
タグ
タイプ
語彙
ユーザー values値を選択して結果を投稿フィルタリングします。 これは、ファセット ウィジェットでファセット用語をクリックするのと同じです。
注
カスタム ファセットは最上位レベルのフィールドを認識します。 オブジェクトと Web コンテンツ構造フィールドはネストされたフィールドとしてインデックス付けされるため、これらのエンティティに対して ネストされた ファセットを選択する必要があります。
たとえば、 日付範囲 ファセットの 範囲 属性は次のとおりです。
{
"ranges": [
{
"label": "range-1",
"range": "[20220411085757 TO 20230413075757]"
},
{
"label": "range-2",
"range": "[20230409085757 TO 20230413075757]"
}
]
}
レスポンスの集計と検索ファセット
GET 検索ではファセットは返されません。 POST 検索の場合、API レスポンスで 集計 と 検索ファセット を確認できます。 集計を表示するには、
リクエストに ファセット構成 を追加すると、検索ファセットが返されます。 たとえば、次のリクエスト本文はタグ ファセットを要求します。
{
"facetConfigurations": [
{
"name": "tag"
}
]
}
レスポンスでは、返される検索ファセットは次のようになります。
"searchFacets": {
"tag": [
{
"displayName": "business",
"term": "business",
"frequency": 26
},
{
"displayName": "fun",
"term": "fun",
"frequency": 1
}
]
}
検索 API へのゲストアクセスを有効にする
API へのゲスト アクセスを有効にするには、 次のように新しいサービス アクセス ポリシー を作成します。
項目 エントリ 名前 検索 有効 チェック済み デフォルト チェック済み タイトル 検索 API へのパブリックアクセス サービスクラス名 com.liferay.portal.search.rest.internal.resource.v1_0.SearchResultResourceImplメッソド名 [postSearchPage または getSearchPage]
関連トピック