ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、こちらまでご連絡ください。

ロールAPIの基本

アプリケーションメニューからロールの作成と管理ができますが、LiferayのREST APIを使うこともできます。役割を管理するには、これらのサービスに連絡してください。

ユーザーを通常のロールに関連付ける

Liferay DXP の新しいインスタンスを起動するには、以下を実行します。

docker run -it -m 8g -p 8080:8080 liferay/dxp:2026.q1.9-lts

http://localhost:8080 に、メールアドレス test@liferay.com とパスワード test を使用して Liferay にサインインします。プロンプトが表示されたら、パスワードを learn に変更してください。

次に、以下の手順に従ってください。

Roles API Basics をダウンロードして解凍します。

curl https://resources.learn.liferay.com/examples/liferay-z3v5.zip -O

unzip liferay-z3v5.zip

ユーザーIDのリストを取得するには、 Users_GET_FromInstance を使用します。通常の役割に関連付けたいユーザーIDをメモしておいてください。
すべてのロール ID のリストを取得するには、 Roles_GET_FromInstance を使用します。関連付けたいロール ID をメモしてください。それは roleType: regular です。例えば、アナリティクス管理者という通常の役割タイプ。
cURLスクリプトを使用して、ユーザーを通常のロールに関連付けます。コマンドラインで、 curl フォルダーに移動します。 RolesAssociationUserAccount_POST_ToInstance.sh スクリプトを実行します。 1234 を通常のロールの ID に置き換えてください。 5678 をユーザーIDに置き換えてください。
```
./RolesAssociationUserAccount_POST_ToInstance.sh 1234 5678
```
グローバルメニュー → コントロールパネル → ロール に移動します。「通常の役割」タブで、ユーザーを関連付けるために使用した特定の役割をクリックします。担当者 タブをクリックします。ユーザーが選択された役割に関連付けられていることを確認してください。
RESTサービスはJavaクライアントを使用して呼び出すこともできます。 curl フォルダから java フォルダに移動します。以下のコマンドを使用してソースファイルをコンパイルしてください。
```
javac -classpath .:* *.java
```
以下のコマンドで RoleUserAssociation_POST_ToInstance.java クラスを実行します。
```
java -classpath .:* -DroleId=1234 -DuserAccountId=5678 RoleUserAssociation_POST_ToInstance
```

cURLコマンドを調べてみましょう

RolesAssociationUserAccount_POST_ToInstance.sh スクリプトは、cURL コマンドを使用して REST サービスを呼び出します。

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/roles/${1}/association/user-account/${2}" \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

このコマンドは以下の引数を取ります。

引数	説明
`-H "Content-Type: application/json"`	リクエストボディのフォーマットがJSONであることを示します。
`-X POST`	指定されたエンドポイントで起動するHTTPメソッド
`"http://localhost:8080/o/headless-admin-user/v1.0/roles/${1}/association/user-account/${2}"`	RESTサービスのエンドポイント
`-u "test@liferay.com:learn"`	基本的な認証情報

注記

ここでは、デモンストレーション目的で基本認証を使用しています。本番環境では、 OAuth2 を介してユーザーを認証する必要があります。 OAuth2 を使用する React アプリケーションの例については、 OAuth2 を使用してユーザーを認証するを参照してください。

他のcURLコマンドも同様のJSON引数を使用しています。

Javaクラスを調べます

RoleUserAssociation_POST_ToInstance.java クラスは、 RoleResource サービスを呼び出すことにより、ユーザーを通常のロールに関連付けます。

public static void main(String[] args) throws Exception {
	RoleResource.Builder builder = RoleResource.builder();

	RoleResource roleResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	roleResource.postRoleUserAccountAssociation(
		Long.valueOf(System.getProperty("roleId")),
		Long.valueOf(System.getProperty("userAccountId")));
}

このクラスは、わずか3行のコードでRESTサービスを呼び出します。

行（省略形）	説明
`RoleResource.Builder builder = ...`	`ビルダー` を取得して、 `ロールリソース` サービスインスタンスを生成します。
`RoleResource roleResource = builder.authentication(...).build();`	基本認証を指定し、 `RoleResource` サービスインスタンスを生成します。
`roleResource.postRoleUserAccountAssociation(...);`	`postRoleUserAccountAssociation` メソッドを呼び出し、データを post に渡します。

プロジェクトには、依存関係としてcom.liferay.headless.admin.user.client.jarファイルが含まれていることに注意してください。すべてのRESTアプリケーションのクライアントJAR依存関係情報は、/o/apiでインストール先のAPIエクスプローラーで確認できます。

注記

main メソッドのコメントは、クラスを実行する方法を示しています。

他の例の Java クラスはこれに似ていますが、異なる RoleResource メソッドを呼び出します。

重要

サービスの詳細については、 RoleResource を参照してください。

以下は、cURLとJavaを使用して他の ロール RESTサービスを呼び出す例です。

インスタンスからロールを取得する

以下のcURLコマンドまたはJavaコマンドを実行することで、役割の一覧を表示できます。

Roles_GET_FromInstance.sh

コマンド：

./Roles_GET_FromInstance.sh

コード：

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/roles" \
	--user "test@liferay.com:learn"

Roles_GET_FromInstance.java

コマンド：

java -classpath .:* Roles_GET_FromInstance

コード：

public static void main(String[] args) throws Exception {
	RoleResource.Builder builder = RoleResource.builder();

	RoleResource roleResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	Page<Role> role = roleResource.getRolesPage(Pagination.of(1, 2));

	System.out.println(role);
}

インスタンスの ロール オブジェクトが JSON に表示されます。スペースロールには、 サブタイプ フィールドも含まれる場合があります。これは、ロールのサブタイプの読み取りと設定で説明されています。

ユーザーをサイトロールに関連付ける

ユーザーを特定のサイトロールに関連付けることができます。 1234 をロールの ID に置き換えてください。 5678 をあなたのサイトの ID に置き換えてください。 9012 をユーザーIDに置き換えてください。

RolesAssociationUserAccount_POST_ToSite.sh

コマンド：

./RolesAssociationUserAccount_POST_ToSite.sh 1234 5678 9012

コード：

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/roles/${1}/association/user-account/${2}/site/${3}" \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

RoleUserAssociation_POST_ToSite.java

コマンド：

java -classpath .:* -DroleId=1234 -DsiteId=5678 -DuserAccountId=9012 RoleUserAssociation_POST_ToSite

コード：

public static void main(String[] args) throws Exception {
	RoleResource.Builder builder = RoleResource.builder();

	RoleResource roleResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	roleResource.postSiteRoleUserAccountAssociation(
		Long.valueOf(System.getProperty("roleId")),
		Long.valueOf(System.getProperty("userAccountId")),
		Long.valueOf(System.getProperty("siteId")));
}

ユーザーを組織の役割に関連付ける

ユーザーを特定の組織内役割に関連付けることができます。 1234 を組織の ID に置き換えてください。 5678 をあなたの役割の ID に置き換えてください。 9012 をユーザーIDに置き換えてください。

RolesAssociationUserAccount_POST_ToOrganization.sh

コマンド：

./RolesAssociationUserAccount_POST_ToOrganization.sh 1234 5678 9012

コード：

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/roles/${1}/association/user-account/${2}/organization/${3}" \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

RoleUserAssociation_POST_ToOrganization.java

コマンド：

java -classpath .:* -DorganizationId=1234 -DroleId=5678 -DuserAccountId=9012 RoleUserAssociation_POST_ToOrganization

コード：

public static void main(String[] args) throws Exception {
	RoleResource.Builder builder = RoleResource.builder();

	RoleResource roleResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	roleResource.postOrganizationRoleUserAccountAssociation(
		Long.valueOf(System.getProperty("roleId")),
		Long.valueOf(System.getProperty("userAccountId")),
		Long.valueOf(System.getProperty("organizationId")));
}

通常の役割の関連付けを削除

特定のユーザーから通常の役割の関連付けを削除します。 1234 をロールの ID に置き換えてください。 5678 をユーザーIDに置き換えてください。

RolesAssociationUserAccount_DELETE_FromInstance.sh

コマンド：

./RolesAssociationUserAccount_DELETE_FromInstance.sh 1234 5678

コード:

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/roles/${1}/association/user-account/${2}" \
	--header "Content-Type: application/json" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

RoleUserAssociation_DELETE_FromInstance.java

コマンド

java -classpath .:* -DroleId=1234 -DuserAccountId=5678 RoleUserAssociation_DELETE_FromInstance

コード：

public static void main(String[] args) throws Exception {
	RoleResource.Builder builder = RoleResource.builder();

	RoleResource roleResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	roleResource.deleteRoleUserAccountAssociation(
		Long.valueOf(System.getProperty("roleId")),
		Long.valueOf(System.getProperty("userAccountId")));
}

サイトロールの関連付けを削除する

特定のユーザーからサイトロールの関連付けを削除します。 1234 をロールの ID に置き換えてください。 5678 をあなたのサイトの ID に置き換えてください。 9012 をユーザーIDに置き換えてください。

RolesAssociationUserAccount_DELETE_FromSite.sh

コマンド：

./RolesAssociationUserAccount_DELETE_FromSite.sh 1234 5678 9012

コード：

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/roles/${1}/association/user-account/${2}/site/${3}" \
	--header "Content-Type: application/json" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

RoleUserAssociation_DELETE_FromSite.java

コマンド

java -classpath .:* -DroleId=1234 -DsiteId=5678 -DuserAccountId=9012 RoleUserAssociation_DELETE_FromSite

コード：

public static void main(String[] args) throws Exception {
	RoleResource.Builder builder = RoleResource.builder();

	RoleResource roleResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	roleResource.deleteSiteRoleUserAccountAssociation(
		Long.valueOf(System.getProperty("roleId")),
		Long.valueOf(System.getProperty("userAccountId")),
		Long.valueOf(System.getProperty("siteId")));
}

組織の役割の関連付けを削除する

特定のユーザーから組織の役割の関連付けを削除します。 1234 を組織の ID に置き換えてください。 5678 をあなたの役割の ID に置き換えてください。 9012 をユーザーIDに置き換えてください。

RolesAssociationUserAccount_DELETE_FromOrganization.sh

コマンド：

./RolesAssociationUserAccount_DELETE_FromOrganization.sh 1234 5678 9012

コード：

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/roles/${1}/association/user-account/${2}/organization/${3}" \
	--header "Content-Type: application/json" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

RoleUserAssociation_DELETE_FromOrganization.java

指示

java -classpath .:* -DorganizationId=1234 -DroleId=5678 -DuserAccountId=9012 RoleUserAssociation_DELETE_FromOrganization

コード：

public static void main(String[] args) throws Exception {
	RoleResource.Builder builder = RoleResource.builder();

	RoleResource roleResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	roleResource.deleteOrganizationRoleUserAccountAssociation(
		Long.valueOf(System.getProperty("roleId")),
		Long.valueOf(System.getProperty("userAccountId")),
		Long.valueOf(System.getProperty("organizationId")));
}

API エクスプローラーには、すべての ロール サービスとスキーマが表示され、各サービスを試すためのインターフェースがあります。

注記

Liferay DXP 2024.Q4+/Portal GA129+ では、外部参照コードを使用して GET/PUT/PATCH/DELETE ロールを実行できます。

ロールのサブタイプの読み取りと設定

注記

サブタイプ フィールドは Liferay DXP 2026.Q3+ で利用可能です。

API では、スペースロールのタイプは roleType: depot です。 depot という名前は、スペース、アセットライブラリ、プロジェクト、デザインライブラリをカバーする役割タイプのプラットフォーム内部名です。そのタイプのロールは、それらのコンテキストのいずれかに関連付ける サブタイプ フィールドを持つことができます。このフィールドは読み取りと書き込みの両方が可能です。その値は、 スペース、 プロジェクト、および デザインライブラリ です。

サブタイプを持たないロールの場合、レスポンスではそのフィールドを空のまま返すのではなく、省略します。これは、標準搭載のスペースロール、およびサブタイプが存在する前に作成されたカスタムロールには存在しません。 Liferay DXP がフィルタリングする場合、null サブタイプ は スペース としてカウントされます。

ロールを作成する際にサブタイプを設定してください。

curl -X POST "http://localhost:8080/o/headless-admin-user/v1.0/roles" \
    -H "Content-Type: application/json" \
    -u "test@liferay.com:learn" \
    -d '{"name": "Project Reviewer", "roleType": "depot", "subtype": "project"}'

呼び出しが成功すると、 201 Created が新しいロールとともに返されます。レスポンスには、次のリクエストに必要な id が含まれます。 GET /o/headless-admin-user/v1.0/roles/{roleId}を使用して値を確認します。その応答には "サブタイプ": "プロジェクト" が含まれます。

同じパスへの PATCH はサブタイプを変更します。 PATCH と PUT は、リクエストが サブタイプ を省略するか、 null として送信する場合、保存された値を保持します。これは重要です。なぜなら、API から読み戻されたロールには、 サブタイプ が null に設定されているからです。サブタイプをクリアするには、空の文字列を送信してください。

Liferay DXPはサービス層でサブタイプを検証するため、同じルールがロールアプリケーションとAPI呼び出しに適用されます。スペース の値は常に受け入れられます。サブタイプ: "プロジェクト" の送信にはコンテンツマーケティングプラットフォーム (CMP) ライセンスが必要であり、 デザインライブラリ には デザインライブラリ リリース機能フラグ (LPD-57283 が必要です。 ) 要件なしでどちらかを送信すると、 400 Bad Requestが返されます。他のサブタイプ値も同様です。レスポンスボディには "タイトル": "ロールサブタイプが無効です。" が含まれています。生成された Java クライアントは Problem.ProblemExceptionを発生させます。その Problem からメッセージを読み取ります。 RoleService の JVM 内呼び出し元は、代わりに RoleSubtypeException を受け取ります。機能フラグを参照してください。

OData式を使用して、役割一覧をサブタイプでフィルタリングする：

curl "http://localhost:8080/o/headless-admin-user/v1.0/roles" \
    --get \
    --data-urlencode "filter=subtype eq 'project'" \
    -u "test@liferay.com:learn"

このフィルターは保存された値のみに一致します。サブタイプを持たないロールは、 サブタイプ の下にインデックス付けされません。 サブタイプ eq 'space' は、標準のスペースロールも、サブタイプが存在する前に作成されたカスタムロールも返しません。すべてのスペースロールにアクセスするには、 types=5 を使用してタイプ別にリストし、クライアントで null-means-space ルールを適用します。

ロールの名前は、「Roles」アプリケーションに表示されるタイトルとは別物です。アプリケーションには スペース管理者がリストされますが、同じ役割は 名前: "アセットライブラリ管理者" を返します。表示タイトルのみが再マッピングされます。表示されているタイトルではなく、 名前 で一致します。同じレスポンスには、 name_i18nとして表示されるタイトル、言語 ID からタイトルへのマップ ({"en-US": "Space Administrator"} ) が含まれます。

この記事の ロール エンドポイントは、すべてのスペースロールを返します。役割一覧の中で、 GET /o/headless-asset-library/v1.0/asset-libraries/{assetLibraryExternalReferenceCode}/roles は、 Depot Role Scoping リリース機能フラグ (LPD-96750) が有効になっている場合、コンテキストによって一覧を絞り込みます。そのエンドポイントは、異なるRoleスキーマを返します。つまり、subtypeが省略され、roleTypeとして文字列「depot」ではなく整数「5」が返されます。上記の headless-admin-user エンドポイントからロールのサブタイプを読み取ります。フィルタリングルールについては、スペースロールサブタイプを参照してください。