APIクエリパラメーター
REST API または GraphQL APIのどちらを使用する場合でも、レスポンスをフィルタリングするのに役立つさまざまなクエリ パラメータが利用可能です。
フィールドパラメーター
このパラメータは、指定されたフィールドのみを指定して返す場合に使用します。 例えば、countries APIにクエリを実行して、2文字の国コードと国名だけを返します。
REST APIの例
cURLリクエスト：
curl \
"http://localhost:8080/o/headless-admin-address/v1.0/countries?fields=a2,name" \
-u "test@liferay.com:learn"
GraphQL APIの例
GraphQLリクエスト：
query {
countries {
actions
items {
a2
name
}
lastPage
page
pageSize
totalCount
}
}
JSON応答：
{
"actions": {},
"facets": [],
"items": [
{
"a2": "CD",
"name": "democratic-republic-of-congo"
},
{
"a2": "ML",
"name": "mali"
},
{
"a2": "BV",
"name": "bouvet-island"
},
{
"a2": "UY",
"name": "uruguay"
},
{
"a2": "SB",
"name": "solomon-islands"
},
{
"a2": "LT",
"name": "lithuania"
},
{
"a2": "LV",
"name": "latvia"
},
{
"a2": "KN",
"name": "st-kitts"
},
{
"a2": "MD",
"name": "moldova"
},
{
"a2": "IO",
"name": "british-indian-ocean-territory"
},
{
"a2": "NP",
"name": "nepal"
},
{
"a2": "SC",
"name": "seychelles"
},
{
"a2": "PH",
"name": "philippines"
},
{
"a2": "AO",
"name": "angola"
},
{
"a2": "MT",
"name": "malta"
},
{
"a2": "SL",
"name": "sierra-leone"
},
{
"a2": "PT",
"name": "portugal"
},
{
"a2": "GG",
"name": "guernsey"
},
{
"a2": "DM",
"name": "dominica"
},
{
"a2": "NF",
"name": "norfolk-island"
}
],
"lastPage": 13,
"page": 1,
"pageSize": 20,
"totalCount": 247
}
フィルターパラメーター
filterパラメーターを使用すると、APIエンドポイントのレスポンスをフィルタリングできます。 例えば、ブログ記投稿をタイトルでフィルタリングできます（例： headline eq 'Able'）。
エンドポイントがフィルタリングをサポートするフィールドを確認するには、スキーマの openapi.json 仕様 の x-filterable をチェックします。 以下に例を示します。
"x-filterable" : {
"dateCreated" : {
"type" : "date_time"
},
"dateModified" : {
"type" : "date_time"
},
"name" : {
"type" : "string"
}
}
Headless API を介してコンテンツをフィルタリングする場合、公開されている カテゴリ のみが含まれます。 内部カテゴリと外部カテゴリは別々にインデックス化されているため、内部カテゴリはフィルタ結果から除外されます。
キーワードとしてインデックスされたフィールドのみがフィルタリングをサポートします。 テキストフィールドでコンテンツを検索するには、代わりに 検索 パラメータを使用してください。 APIエクスプローラー を使用して、APIのパラメータを調べます。
カスタムオブジェクトのフィルタリングには、Liferay DXP 2025.Q1以降/Portal GA132以降が必要です。 ObjectEntry クラス名を完全に使用し、 taskItemDelegateName パラメーター にオブジェクト名を含めることを忘れないでください。
REST APIの例
cURLリクエスト：
curl \
"http://localhost:8080/o/headless-delivery/v1.0/sites/20121/blog-postings?fields=articleBody,headline&filter=headline%20eq%20%27Able%27" \
-u "test@liferay.com:learn"
GraphQL APIの例
GraphQLリクエスト：
query {
blogPostings(filter: "headline eq 'Able'", siteKey: "20121") {
page
items {
articleBody
headline
}
}
}
JSON応答：
"data": {
"blogPostings": {
"page": 1,
"items": [
{
"articleBody": "<p>Able able able</p>",
"headline": "Able"
}
]
}
}
フィルタリングには、さまざまな演算子を使用できます。
比較演算子
| 演算子 | 説明 | 例 |
|---|---|---|
eq | 等しい | addressLocality eq 'Redmond' |
eq | nullに等しい | addressLocality eq null |
ne | 等しくない | addressLocality ne 'London' |
ne | nullではない | addressLocality ne null |
gt | 次の値より大きい | price gt 20 |
ge | 以上 | price ge 10 |
lt | 次の値より小さい | dateCreated lt 2018-02-13T12:33:12Z |
le | 以下 | dateCreated le 2012-05-29T09:13:28Z |
論理演算子
| 演算子 | 説明 | 例 |
|---|---|---|
and | ロジカルで | price le 200 and price gt 3.5 |
or | ロジカルまたは | price le 3.5 or price gt 200 |
not | ロジカルでない | not (price le 3.5) |
notの演算子の後にスペース文字が必要です。
グループ化演算子
| 演算子 | 説明 | 例 |
|---|---|---|
( ) | 優先グループ化 | (price eq 5) or (addressLocality eq 'London') |
文字列関数
| 関数 | 説明 | 例 |
|---|---|---|
contains | が以下を含む | contains(title,'edmon') |
startswith | 次で開始 | startswith(addressLocality, 'Lond') |
ラムダ演算子
ラムダ演算子は、コレクションフィールド（例えば、リソースの キーワード）に対してブール値式を評価します。 コレクションを識別するためのナビゲーションパスを先頭に追加する必要があります。
| ラムダ演算子 | 説明 | 例 |
|---|---|---|
any | 任意 | keywords/any(k:contains(k,'news')) |
any 演算子は、各コレクション要素にブール値式を適用し、いずれかの要素に対して式がtrueであれば true と評価します。
演算子の組み合わせとODataの構文
構文例やその他の演算子の組み合わせについては、 OData 標準リファレンス を参照してください。
パラメーターのフラット化
このパラメータを使用すると、階層構造内のアイテムを取得できます。たとえば、親ユーザーグループとその子ユーザーグループを取得する場合などに使用します。 例えば、Raylife Globalは、様々な地域Raylife組織の親組織としての役割を果たしています。
REST APIの例
cURLリクエスト：
curl \
"http://localhost:8080/o/headless-admin-user/v1.0/organizations?fields=id,name&flatten=true" \
-u "test@liferay.com:learn"
GraphQL APIの例
GraphQLリクエスト：
query {
organizations(flatten: true) {
actions
items {
id
name
}
lastPage
page
pageSize
totalCount
}
}
JSON応答：
{
"actions": {
// Actions data...
},
"facets": [],
"items": [
{
"id": "46367",
"name": "Raylife APAC"
},
{
"id": "46372",
"name": "Raylife EMEA"
},
{
"id": "46377",
"name": "Raylife LATAM"
},
{
"id": "46382",
"name": "Raylife NA"
},
{
"id": "46616",
"name": "Raylife Global"
}
],
"lastPage": 1,
"page": 1,
"pageSize": 20,
"totalCount": 5
}
ページおよびページサイズパラメーター
これらのパラメータを使用して、どの項目のサブセットを返すかを指定します。 page パラメータは、利用可能なすべてのページのうち、どのページを返すかを指定します。 pageSizeパラメーターは、ページごとに必要な項目数を指定します。 例えば、 pageSize=10 と page=22 （つまり項目の22ページ目）について、countries APIにクエリを実行します。
REST APIの例
cURLリクエスト：
curl \
"http://localhost:8080/o/headless-admin-address/v1.0/countries?fields=a2,name&page=22&pageSize=10" \
-u "test@liferay.com:learn"
GraphQL APIの例
GraphQLリクエスト：
query {
countries(page: 22, pageSize: 10) {
actions
items {
a2
name
}
lastPage
page
pageSize
totalCount
}
}
JSON応答：
{
"actions": {},
"facets": [],
"items": [
{
"a2": "KG",
"name": "kyrgyzstan"
},
{
"a2": "RE",
"name": "reunion-island"
},
{
"a2": "CK",
"name": "cook-islands"
},
{
"a2": "ER",
"name": "eritrea"
},
{
"a2": "GE",
"name": "georgia"
},
{
"a2": "MW",
"name": "malawi"
},
{
"a2": "CO",
"name": "colombia"
},
{
"a2": "GW",
"name": "guinea-bissau"
},
{
"a2": "SN",
"name": "senegal"
},
{
"a2": "TW",
"name": "taiwan"
}
],
"lastPage": 25,
"page": 22,
"pageSize": 10,
"totalCount": 247
}
検索パラメーター
このパラメータを使用して、検索語で項目を絞り込みます。 例えば、 unitedという検索語について、countries API を検索します。
REST APIの例
cURLリクエスト：
curl \
"http://localhost:8080/o/headless-admin-address/v1.0/countries?fields=a2,name&search=united" \
-u "test@liferay.com:learn"
GraphQL APIの例
GraphQLリクエスト：
query {
countries(search: "united") {
actions
items {
a2
name
}
lastPage
page
pageSize
totalCount
}
}
JSON応答：
{
"actions": {},
"facets": [],
"items": [
{
"a2": "GB",
"name": "united-kingdom"
},
{
"a2": "US",
"name": "united-states"
},
{
"a2": "UM",
"name": "united-states-minor-outlying-islands"
},
{
"a2": "VI",
"name": "united-states-virgin-islands"
},
{
"a2": "AE",
"name": "united-arab-emirates"
}
],
"lastPage": 1,
"page": 1,
"pageSize": 20,
"totalCount": 5
}
ソートパラメーター
sortパラメーターを使用して、APIエンドポイントの応答を昇順（asc）または降順（desc）にソートすることができます。 APIエクスプローラー を使用して、APIのパラメータを調べます。
複数のパラメーターでソートする場合は、パラメーター名をカンマで区切り、重要度で並べます。 例えば、最初にタイトルで、次に作成日でソートするには、sort=title,dataCreatedをリクエストに追加します。
1つのパラメーターにのみ降順を指定する場合、他のパラメーターには明示的に昇順のソート順（:asc）を指定する必要があります。 例えば、sort=headline:desc,dateCreated:ascです。
以下の例では、countries API応答を名前の降順でソートしています。
REST APIの例
cURLリクエスト：
curl \
"http://localhost:8080/o/headless-admin-address/v1.0/countries?fields=a2,name&sort=name:desc" \
-u "test@liferay.com:learn"
GraphQL APIの例
GraphQLリクエスト：
query {
countries(sort: "name:desc") {
actions
items {
a2
name
}
lastPage
page
pageSize
totalCount
}
}
JSON応答：
{
"actions": {},
"facets": [],
"items": [
{
"a2": "ZW",
"name": "zimbabwe"
},
{
"a2": "ZM",
"name": "zambia"
},
{
"a2": "YE",
"name": "yemen"
},
{
"a2": "WS",
"name": "western-samoa"
},
{
"a2": "EH",
"name": "western-sahara"
},
{
"a2": "WF",
"name": "wallis-futuna"
},
{
"a2": "VN",
"name": "vietnam"
},
{
"a2": "VE",
"name": "venezuela"
},
{
"a2": "VA",
"name": "vatican-city"
},
{
"a2": "VU",
"name": "vanuatu"
},
{
"a2": "UZ",
"name": "uzbekistan"
},
{
"a2": "UY",
"name": "uruguay"
},
{
"a2": "VI",
"name": "united-states-virgin-islands"
},
{
"a2": "UM",
"name": "united-states-minor-outlying-islands"
},
{
"a2": "US",
"name": "united-states"
},
{
"a2": "GB",
"name": "united-kingdom"
},
{
"a2": "AE",
"name": "united-arab-emirates"
},
{
"a2": "UA",
"name": "ukraine"
},
{
"a2": "UG",
"name": "uganda"
},
{
"a2": "TV",
"name": "tuvalu"
}
],
"lastPage": 13,
"page": 1,
"pageSize": 20,
"totalCount": 247
}
関連オブジェクトデータによるソート
Liferay DXP 2024.Q3+/Portal GA125+
オブジェクトAPIは、関連オブジェクトのフィールドを使用してエントリをソートすることをサポートしており、データ取得の柔軟性を向上させます。
これは、一対多および多対一のリレーションシップを持つカスタムオブジェクトを使用することで実現できます。 並べ替えは、テキスト、長文テキスト、日付、日時、整数、長整数、小数、小数点以下桁数、ブール値、選択リストなど、さまざまなフィールドタイプで行うことができます。
作成者、作成日、外部参照コード、ID、更新日、ステータスなどのシステムフィールドもサポートされています。
関連オブジェクトのソート構文は、次のパターンに従います。
sort=relatedRelationship/fieldName:asc
複数の関連オブジェクトのフィールドに基づいて、リレーションシップを連鎖させることで並べ替えることもできます。
sort=relatedRelationship1/relatedRelationship2/fieldName:desc
カスタムオブジェクト Student があり、それが別のカスタムオブジェクト University と多対一の関係にあるとします。 学生を 大学名 で昇順に並べ替えるには、次のコマンドを使用できます。
curl \
"http://localhost:8080/o/c/students?sort=universityEnrolled/universityName:asc" \
--header "Accept: application/json" \
--user "test@liferay.com:learn"
このコマンドでは、 universityEnrolled は、各学生に関連付けられている大学を表す関係です。 universityName は、 University オブジェクトのフィールドで、Student エントリをソートするために使用します。 :asc は、昇順でソートすることを指定します。
JSONレスポンスは以下のようになります。
{
...
"taxonomyCategoryBriefs" : [ ],
"universityEnrolledERC" : "029520e6-d34d-5140-9bc5-b81f5ae29f9d",
"r_universityEnrolled_c_universityId" : 31963,
"r_universityEnrolled_c_universityERC" : "029520e6-d34d-5140-9bc5-b81f5ae29f9d",
"studentName" : "August"
...
"taxonomyCategoryBriefs" : [ ],
"universityEnrolledERC" : "62e78f42-1596-8f11-beb5-4b34e719b8a9",
"r_universityEnrolled_c_universityId" : 31955,
"r_universityEnrolled_c_universityERC" : "62e78f42-1596-8f11-beb5-4b34e719b8a9",
"studentName" : "Nathaly"
...
"taxonomyCategoryBriefs" : [ ],
"universityEnrolledERC" : "62e78f42-1596-8f11-beb5-4b34e719b8a9",
"r_universityEnrolled_c_universityId" : 31955,
"r_universityEnrolled_c_universityERC" : "62e78f42-1596-8f11-beb5-4b34e719b8a9",
"studentName" : "Luke"
...
"taxonomyCategoryBriefs" : [ ],
"universityEnrolledERC" : "d29da38c-1adf-4aba-1129-463d8f4e6b50",
"r_universityEnrolled_c_universityId" : 31961,
"r_universityEnrolled_c_universityERC" : "d29da38c-1adf-4aba-1129-463d8f4e6b50",
"studentName" : "Peter"
...
"taxonomyCategoryBriefs" : [ ],
"universityEnrolledERC" : "d0ce2764-6804-8de8-ff9f-4b199867dc4f",
"r_universityEnrolled_c_universityId" : 31957,
"r_universityEnrolled_c_universityERC" : "d0ce2764-6804-8de8-ff9f-4b199867dc4f",
"studentName" : "Larissa"
...
"taxonomyCategoryBriefs" : [ ],
"universityEnrolledERC" : "2ff3dc43-a871-8eed-6204-5c7ef0302e7a",
"r_universityEnrolled_c_universityId" : 31959,
"r_universityEnrolled_c_universityERC" : "2ff3dc43-a871-8eed-6204-5c7ef0302e7a",
"studentName" : "Manu"
...
}
universityName フィールドは返されませんが、エントリはマッピングされた r_universityEnrolled_c_universityId 値に基づいてアルファベット順にソートされます。これらの値は大学名に対応しています。
| 大学ID | 大学名 |
|---|---|
| 31963 | カリフォルニア工科大学 |
| 31955 | ハーバード大学 |
| 31961 | MIT |
| 31957 | オックスフォード |
| 31959 | スタンフォード |