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'）。
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 | ヌルではない | 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+/ポータル GA125+
オブジェクト API は、関連オブジェクトのフィールドを使用してエントリを並べ替えることをサポートし、データ取得の柔軟性を高めます。
これは、1 対多および多対 1 の関係を持つカスタム オブジェクトで実行できます。 並べ替えは、テキスト、長いテキスト、日付、日付と時刻、整数、長い整数、小数、精度小数、ブール値、選択リストなど、さまざまなフィールド タイプで実行できます。
作成者、作成日、外部参照コード、ID、変更日、ステータスなどのシステム フィールドもサポートされています。
関連オブジェクトの並べ替え構文は次のパターンに従います。
sort=relatedRelationship/fieldName:asc
関係を連鎖させることで、複数の関連オブジェクトのフィールドで並べ替えることもできます。
sort=relatedRelationship1/relatedRelationship2/fieldName:desc
別のカスタム オブジェクト Universityと多対 1 の関係を持つカスタム オブジェクト Student があるとします。 学生を universityName で昇順に並べ替えるには、次のコマンドを使用します。
curl \
"http://localhost:8080/o/c/students?sort=universityEnrolled/universityName:asc" \
--header "Accept: application/json" \
--user "test@liferay.com:learn"
このコマンドでは、 universityEnrolled は各学生に関連付けられた大学を表す関係です。 universityName は、学生のエントリを並べ替える基準となる University オブジェクト内のフィールドです。 :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 | マサチューセッツ工科大学 |
| 31957 | オックスフォード |
| 31959 | スタンフォード |