オブジェクトAPIの基本
オブジェクトを公開すると、Liferay はそのオブジェクトに対応する REST API を自動的に生成します。 これらの API は、会社スコープオブジェクトとサイトスコープオブジェクトで異なりますが、すべて c/[pluralobjectlabel] という命名パターンを使用します (例: c/timeoffrequests)。 これらのAPIを使用して、オブジェクトエントリの作成、アクセス、更新、および削除を行います。
cURLコマンドを使用して、カスタムオブジェクトに対する基本的なCRUD操作を実行します。 先に進む前に、Liferayインスタンスをセットアップし、サンプルコードを準備します。
サイト および 会社 オブジェクト用に生成された API の完全なリストについては、 オブジェクトのヘッドレス フレームワーク統合 を参照してください。 Liferay API Explorerを使用してカスタムオブジェクトAPIを表示およびテストするには、 [server]:[port]/o/api (例: localhost:8080/o/api) にアクセスしてください。 これらは REST アプリケーション の下に表示されます。
Liferayインスタンスのセットアップ
新しいLiferay インスタンスを起動し、以下を実行します。
docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.132-ga132
http://localhost:8080 で Liferay にサインインしてください。 メールアドレス test@liferay.com とパスワード test を使用してください。 プロンプトが表示されたら、パスワードを learnに変更します。
次に、以下の手順に従って、このチュートリアルの基本オブジェクトを作成します：
-
グローバルメニュー (
) → コントロールパネル → オブジェクト をクリックします。 -
新規 をクリックし、以下の値を入力してください。
項目 値 ラベル Able複数形のラベル Ables名前 Able -
新しい オブジェクト ドラフトを選択し、 フィールド タブに移動して、テキスト フィールドを 1 つ追加します。
ラベル 項目名 種類 必須 名前 名前 テキストボックス ✔ -
詳細 タブに移動し、 公開 をクリックします。
重要このチュートリアルでは、上記の値を使用する必要があります。
オブジェクトを公開すると データの受信と保存のための新しいアプリケーションが作成され、アクティブ化されます。 ヘッドレスAPI経由でアクセスできるようになりました。
サンプルコードを準備する
以下のコマンドを実行して、提供されたサンプルコードをダウンロードし、解凍してください。
curl https://resources.learn.liferay.com/examples/liferay-v1s4.zip -O
unzip liferay-v1s4.zip
これらのスクリプトには、以下のAPIが含まれています。
| HTTP メソッド | HTTPエンドポイント | 説明 |
|---|---|---|
| GET | / | Liferayインスタンス内のオブジェクトエントリの完全なリストを返します。結果はページ分割、フィルタリング、検索、およびソートが可能です。 |
| POST | / | API呼び出しで提供された詳細情報を使用して、新しいオブジェクトエントリを作成します。 |
| DELETE | /{objectNameId} | 指定されたオブジェクトエントリを削除し、操作が成功した場合は204を返します。 |
| GET | /{objectNameId} | 指定されたオブジェクトエントリの詳細を返します |
| PUT | /{objectNameId} | 指定されたオブジェクトエントリの詳細を、API呼び出しで提供された情報に置き換えます。 |
| GET | /{objectNameId}/permissions | 指定されたオブジェクトのエントリ権限の詳細を返します |
| PUT | /{objectNameId}/permissions | 指定されたオブジェクトエントリの権限の詳細を、API呼び出しで提供された権限の詳細に置き換えます。 |
カスタムオブジェクトのAPIを呼び出す
-
サンプルコードをダウンロード後、
liferay-v1s4プロジェクト内のcurlフォルダに移動します。cd liferay-v1s4/curl -
Ables_POST_ToCompanyを実行します。 これにより、3つのエントリーが作成されます。./Ables_POST_ToCompany.shターミナルには、新しく作成されたエントリーの完全なスキーマが表示されます。 次のメソッドで使用するために、最初のエントリーのIDをコピーします。
{ "id" : 41969, ... "name" : "Able 1" } { "id" : 41971, ... "name" : "Able 2" } { "id" : 41973, ... "name" : "Able 3" } -
Ables_GET_FromCompanyを実行します。 オブジェクトエントリーのリストが返されます。./Ables_GET_FromCompany.sh -
最初のエントリの ID をパラメータとして
Ables_PUT_ByIdを実行します。 これにより、指定されたエントリーの詳細がAPI呼び出しで提供された詳細に置き換えられます。./Ables_PUT_ById.sh {entry-id}{ "id" : 41969, ... "name" : "Able One" } -
パラメータと同じ ID を使用して
Ables_DELETE_ByIdを実行します。 これにより、指定したエントリーが削除されます。./Ables_DELETE_ById.sh {entry-id} -
パラメータと同じ ID を使用して
Ables_GET_ByIdを実行します。 これにより、指定されたエントリーが存在する場合はその詳細が返されます。./Ables_GET_ById.sh {entry-id}前の手順でエントリーを削除したため、次のメッセージが返されます。
{ "status": "NOT_FOUND", "title": "No ObjectEntry exists with the primary key 41969" }
サンプルのcURLスクリプトの検証
以下は、チュートリアルのcURLコマンドの例です。
インスタンスにPOST Ablesを送信
curl \
"http://localhost:8080/o/c/ables/" \
--data-raw '
{
"name": "Able 1"
}' \
--header "Content-Type: application/json" \
--request "POST" \
--user "test@liferay.com:learn"
curl \
"http://localhost:8080/o/c/ables/" \
--data-raw '
{
"name": "Able 2"
}' \
--header "Content-Type: application/json" \
--request "POST" \
--user "test@liferay.com:learn"
curl \
"http://localhost:8080/o/c/ables/" \
--data-raw '
{
"name": "Able 3"
}' \
--header "Content-Type: application/json" \
--request "POST" \
--user "test@liferay.com:learn"
ID でエイブルを配置する
curl \
"http://localhost:8080/o/c/ables/${1}" \
--data-raw '
{
"name": "Able One"
}' \
--header "Content-Type: application/json" \
--request "PUT" \
--user "test@liferay.com:learn"
オブジェクト権限の管理
オブジェクトAPIを使用して、オブジェクトエントリの権限を読み取り、更新します。 詳細については、 オブジェクト アプリケーション権限 を参照してください。
-
オブジェクトエントリの権限のリストを取得するには、
Ables_GET_Permissionsを実行します。./Ables_GET_Permissions.sh {entry-id}この例では、すべてのロールに対する権限が返されます。 特定のロールの権限を取得するには、
roleNamesクエリ パラメーターを使用します。curl \ "http://localhost:8080/o/c/ables/${1}/permissions?roleNames=Site%20Member" \ --user "test@liferay.com:learn"この例では、唯一の役割は 所有者であり、その権限は削除、権限、更新、および表示です。
{ "actions": { "get": { "method": "GET", "href": "http://localhost:8080/o/c/ables/41969/permissions" }, "replace": { "method": "PUT", "href": "http://localhost:8080/o/c/ables/41969/permissions" } }, "facets": [], "items": [ { "actionIds": [ "DELETE", "PERMISSIONS", "UPDATE", "VIEW" ], "roleName": "Owner" } ], "lastPage": 1, "page": 1, "pageSize": 1, "totalCount": 1 } -
エントリ ID をパラメータとして
Ables_PUT_Permissionsを実行して、エントリの詳細を API 呼び出しで提供されたものに置き換えます。./Ables_PUT_Permissions.sh {entry-id}更新権限は所有者ロールから削除されました。
{ "actions": { "get": { "method": "GET", "href": "http://localhost:8080/o/c/ables/41969/permissions" }, "replace": { "method": "PUT", "href": "http://localhost:8080/o/c/ables/41969/permissions" } }, "facets": [], "items": [ { "actionIds": [ "DELETE", "PERMISSIONS", "VIEW" ], "roleName": "Owner" } ], "lastPage": 1, "page": 1, "pageSize": 1, "totalCount": 1 }
タグとカテゴリの管理
オブジェクトAPIを使用して、分類が有効になっているオブジェクトエントリのタグとカテゴリを読み取り、設定、更新します。 詳細については、 タグとカテゴリ を参照してください。
タグは、 キーワード プロパティで表されます。 タグを設定または更新するには、POST、PUT、またはPATCHリクエストの本文に キーワード 配列を追加します。
"keywords" : [
"tag1", "tag2", "tag3"
]
オブジェクトエントリに対してGETリクエストを行った後、同じ キーワード 配列でそのタグを読み取ることができます。
オブジェクトエントリのカテゴリを設定および更新するには、POST、PUT、またはPATCHリクエストに taxonomyCategoryIds 配列を追加します。
"taxonomyCategoryIds" : [
1234, 5678
]
オブジェクトエントリにカテゴリを割り当てるには、既存のカテゴリ語彙が必要です。 詳細については、 コンテンツのカテゴリと語彙の定義 を参照してください。
オブジェクトエントリの GET リクエストを行った後、 taxonomyCategoryBriefs 配列でそのカテゴリを読み取ります。この配列には、割り当てられた各カテゴリの taxonomyCategoryId と taxonomyCategoryName が含まれています。
entryReference ネストされたフィールドの動作には、Liferay DXP 2026.Q1 以降が必要です。 以前のバージョンでは、オブジェクトのJSONをエクスポートする際にこれらの値が省略され、インポートしても効果がありません。
entryReference ネストされたフィールドには、関連付けられたオブジェクトエントリの外部参照コードと、そのスコープ (サイト、アセットライブラリ、または Liferay インスタンス) も含まれます。 同じ JSON がインポートされると、これらのカテゴリはインポートされたオブジェクトエントリに自動的に関連付けられます（存在しない場合は、対応する空のカテゴリが作成されます）。
"taxonomyCategoryBriefs": [
{
"taxonomyCategoryId": 1234,
"taxonomyCategoryName": "Category A",
"entryReference":
{
"externalReferenceCode": "entryerc-1234-5678-1234-123456789012",
"scope": {
"externalReferenceCode": "siteerc1-1234-5678-1234-123456789012",
"type:" "Site"
}
}
},
{
"taxonomyCategoryId": 5678,
"taxonomyCategoryName": "Category B",
"entryReference":
{
"externalReferenceCode": "entryerc-5678-1234-5678-678901234567",
"scope": {
"externalReferenceCode": "siteerc2-5678-1234-5678-678901234567",
"type": "Site"
}
}
}
]
キーワード と taxonomyCategoryIds でオブジェクトエントリをフィルタリングします。ルールは API クエリ パラメータ に記載されています。 フィルタ文字列の例は次のようになります。
-
keywords/any(k:k in ('tag1','tag2'))は、tag1またはtag2でタグ付けされたすべてのオブジェクトエントリを取得します。 -
taxonomyCategoryIds/any(k:k in (1234,5678))は、ID1234または5678のカテゴリにリンクされているすべてのエントリを取得します。
APIクエリパラメータ で説明されている構文を使用して、関連オブジェクトのフィールドでオブジェクトエントリをソートします。 ソート文字列の例は次のようになります。
-
sort=relatedRelationship/fieldName:ascは、直接関連するオブジェクトのフィールドに基づいてエントリを昇順にソートします。 -
sort=relatedRelationship1/relatedRelationship1/fieldName:descは、ネストされた関連オブジェクトのフィールドに基づいてエントリを降順にソートします。
コメントの管理
Liferay DXP 2026.Q2
オブジェクト定義でコメントが有効になっている場合、ヘッドレスAPIを介してオブジェクトエントリのコメントを管理できます。 コメント機能を有効にするには、以下の手順に従ってください。
これらのエンドポイントは、サイトスコープのオブジェクト定義でのみ利用可能です。 この記事の前半で Able オブジェクトを作成した場合、それは会社スコープです。続行する前に、新しいサイトスコープのオブジェクト定義を作成し、少なくとも 1 つのエントリを追加して、エントリの外部参照コードをメモしてください。
-
グローバルメニュー (
) → コントロールパネル → オブジェクト をクリックします。 -
オブジェクト定義を選択してください。
-
詳細タブで、 コメントを有効にする を切り替えます。
-
保存 または 公開 をクリックします。
-
Liferay API Explorer を
[server]:[port]/o/apiで開きます (例:localhost:8080/o/api)。 -
REST アプリケーション をクリックし、オブジェクト定義を選択します。
-
利用可能なエンドポイントを確認するには、 コメント セクションを展開してください。
コメントが有効になったら、オブジェクトのヘッドレスエンドポイントを使用して、外部参照コード (ERC) を使用してエントリ コメントに対して GET、 POST、 PUT、および DELETE 操作を実行します。 コメントリソースは、コメントへのスレッド形式の返信を管理するための子コメントエンドポイントも公開しています。
nestedFields パラメータを使用して追加の詳細を取得する
一部の情報は、オブジェクトのAPIレスポンスにネストされたフィールドとして埋め込まれています。
| パラメータ値 | 説明 |
|---|---|
nestedFields=[fieldName].fileBase64 | 添付ファイルフィールド の Base64 エンコードを返します。 |
nestedFields=[fieldName].folder | Base64エンコードされた添付ファイルが保存されているフォルダ を返します。 |
nestedFields=auditEvents | エントリ履歴が有効になっている場合、エントリ の監査イベント を返します。 |
nestedFields=[firstObjectRelationship],[secondObjectRelationship] | に関連するオブジェクトエントリ を返します。 |
nestedFields=profileURL | エントリ作成ユーザーのプロフィールURLを返します。 |
nestedFields=permissions | エントリの役割と権限を返します（Liferay DXP 2024.Q4以降/Portal GA129以降で利用可能）。 |
nestedFields=comments | エントリコメント を返します（サイトスコープのオブジェクト定義でのみ使用可能）。 |
例えば、エンドポイント http://localhost:8080/o/c/ables/41969?nestedFields=permissions を呼び出すと、API レスポンスに permissions 要素が返されます。
"permissions" : [ {
"actionIds" : [ "DELETE", "PERMISSIONS", "UPDATE", "VIEW" ],
"roleName" : "Owner"
} ],