REST APIリファレンス > プラットフォームREST APIバージョン3リソース > ユーザーグループ
  

ユーザーグループ

このリソースを使用して、ユーザーグループを作成、更新および削除します。
userGroupsリソースをusersおよびrolesリソースとともに使用して、ユーザー特権を管理します。ユーザーとグループは割り当てられているロールに基づいて、タスクを実行し、アセットにアクセスする事ができます。
次の要求を送信できます。
注: このリソースは、動的レート制限を使用します。システムで大量の要求またはサイズが発生すると、応答が遅くなったり、「要求が多すぎます」というエラーメッセージが表示されて失敗したりすることがあります。
usersおよびroles REST APIリソースの詳細は、次のトピックを参照してください。
users、user groupsおよびrolesの全般的な情報については、Administratorのヘルプを参照してください。
注: ユーザー、ユーザーグループ、結合されたロールの数は、1つの組織で1000を超える事は出来ません。

ユーザーグループの詳細の取得

組織内のすべてのユーザーグループの詳細、または特定のユーザーグループの詳細を要求できます。

GET要求

組織内のすべてのユーザーグループの詳細、または特定のユーザーグループの詳細を要求できます。
ユーザーグループの詳細を取得するには、次のURIを使用します。
/public/core/v3/userGroups
特定のユーザーグループの詳細を取得するには、次のクエリパラメータをURIに追加する事ができます。
パラメータ
タイプ
説明
q
文字列
クエリフィルタ。次のいずれかのフィールドを使用してフィルタできます。
  • - userGroupId。ユーザーグループを一意に識別するID。
  • - userGroupName。ユーザーグループの名前。
limit
Int
返すユーザーグループの最大数。
デフォルトは100です。
skip
Int
結果のリストのオフセットの量。
デフォルトは0です。
例えば、ユーザーグループの名前を使用して特定のユーザーグループの詳細を取得するには、次の要求を使用できます。
public/core/v3/userGroups?q=userGroupName=="group_a"

GET応答

正常に実行された場合は、各ユーザーグループの次の情報を返します。
フィールド
タイプ
説明
id
文字列
ユーザーグループID。
orgId
String
ユーザーグループが属する組織のID。
createdBy
文字列
ユーザーアカウントを作成したユーザー。
updatedBy
String
ユーザーアカウントを最後に更新したユーザー。
createTime
文字列
ユーザーグループを作成した日時。
updateTime
文字列
ユーザーグループが最後に更新された日時。
userGroupName
文字列
ユーザーグループの名前。
description
文字列
ユーザーグループの説明。
roles
配列
ユーザーグループに割り当てられたロール。
id
文字列
rolesオブジェクトに含まれます。
ロールID。
roleName
文字列
rolesオブジェクトに含まれます。
ロール名。
description
文字列
rolesオブジェクトに含まれます。
ロールの説明。
displayName
String
rolesオブジェクトに含まれます。
ユーザーインタフェースに表示されるロール名。
displayDescription
String
rolesオブジェクトに含まれます。
ユーザーインタフェースに表示されるロールの説明。
users
配列
ユーザーグループに割り当てられたユーザー。
id
文字列
usersオブジェクトに含まれます。
ユーザーID。
userName
文字列
usersオブジェクトに含まれます。
ユーザー名。
description
文字列
usersオブジェクトに含まれます。
ユーザーの説明。

GET応答の例

成功した場合、次の例のような応答を受信します。
[
{
"id": "a6x85hoMvH2kWUIlcIRBEh",
"orgId": "cPYWk02I4aBeuLEvYRtaMS",
"createdBy": "a@abc.com",
"updatedBy": "a@abc.com",
"createTime": "2019-03-19T17:27:09.000Z",
"updateTime": "2019-03-19T17:27:09.000Z",
"userGroupName": "group_a",
"description": "",
"roles": [
{
"id": "9gedBDoYQoQibNMohf5KCh",
"roleName": "Admin",
"description": "Role for performing administrative tasks for an organization. Has full access to all licensed services."
"displayName": "Admin",
"displayDescription": "Role for performing administrative tasks for an organization. Has full access to all licensed services."
}
],
"users": [
{
"id": "5N9JGth6pRYfOGjGKv3Q2D",
"userName": "a@abc.com",
"description": ""
}
]
}
]

ユーザーグループの作成

管理者権限がある場合は、userGroupsリソースを使用してユーザーグループを作成できます。
注: ユーザー、ユーザーグループ、結合されたロールの数は、1つの組織で1000を超える事は出来ません。

POST要求

ユーザーグループを作成するには、次のURIを使用してPOST要求を送信します。
/public/core/v3/userGroups
以下の情報を含めます。
フィールド
タイプ
必須
説明
name
String
○
ユーザーグループの名前。
description
文字列
-
ユーザーグループの説明。
roles
配列
はい
ユーザーグループに割り当てるロールのID。
users
配列
-
ユーザーグループに割り当てるユーザーのID。

POST応答

成功した場合、userGroupsオブジェクトと、POST要求に含めた詳細が返されます。

POSTの例

ユーザーグループを作成するには、次の例のような要求を送信します。
POST <baseApiUrl>/public/core/v3/userGroups
Content-Type: application/json
Accept: application/json
INFA-SESSION-ID: <sessionId>
{
"name" : "user_group_1",
"roles" : ["5IPgtye09EbiWqz5XXuzwC", "9gedBDoYQoQibNMohf5KCh"],
"users" : ["9EcgvBYZ9GGflOYr98GzOH"]
}
次の例のような応答を受信します。
{
"id": "0TLmCMwX0jNdJ5SzlQC2CW",
"orgId": "cPYWk02I4aBeuLEvYRtaMS",
"createdBy": "a@abc.com",
"updatedBy": "a@abc.com",
"createTime": "2019-03-20T18:30:32.457Z",
"updateTime": "2019-03-20T18:30:32.472Z",
"userGroupName": "user_group_1",
"description": null,
"roles": [
{
"id": "9gedBDoYQoQibNMohf5KCh",
"roleName": "Admin",
"description": "Role for performing administrative tasks for an organization. Has full access to all licensed services."
"displayName": "Admin",
"displayDescription": "Role for performing administrative tasks for an organization. Has full access to all licensed services."
},
{
"id": "5IPgtye09EbiWqz5XXuzwC",
"roleName": "test_user_1",
"description": ""
"roleName": "test_user_1",
"description": ""
}
],
"users": [
{
"id": "9EcgvBYZ9GGflOYr98GzOH",
"userName": "test_user_2",
"description": null
}
]
}

ユーザーグループの更新

ユーザーとロールをユーザーグループに追加したり、ユーザーとロールをユーザーグループから削除したりできます。

ロールの追加

ユーザーグループにロールを追加するには、次のURIのいずれかを使用してPUT要求を送信します。
/public/core/v3/userGroups/<user group ID>/addRoles
/public/core/v3/userGroups/name/<user group name>/addRoles
ユーザーグループに追加するロールの配列を含めます。
ユーザーグループにロールを追加するには、次の例のような要求を送信します。
PUT <baseApiUrl>/public/core/v3/userGroups/cPYWk02I4aBeuLEvYRtaMS/addRoles
Content-Type: application/json
Accept: application/json
INFA-SESSION-ID: <sessionId>
{
"roles" : ["Admin", "Business Manager"]
}

ロールの削除

ユーザーグループからロールを削除するには、次のURIのいずれかを使用してPUT要求を送信します。
/public/core/v3/userGroups/<user group ID>/removeRoles
/public/core/v3/userGroups/name/<user group name>/removeRoles
ユーザーグループから削除するロールの配列を含めます。
ユーザーグループからロールを削除するには、次の例のような要求を送信します。
PUT <baseApiUrl>/public/core/v3/userGroups/cPYWk02I4aBeuLEvYRtaMS/removeRoles
Content-Type: application/json
Accept: application/json
INFA-SESSION-ID: <sessionId>
{
"roles" : ["Admin", "Business Manager"]
}

ユーザーの追加

ユーザーグループにユーザーを追加するには、次のURIのいずれかを使用してPUT要求を送信します。
/public/core/v3/userGroups/<user group ID>/addUsers
/public/core/v3/userGroups/name/<user group name>/addUsers
ユーザーグループに追加するユーザー名の配列を含めます。
ユーザーグループにユーザーを追加するには、次の例のような要求を送信します。
PUT <baseApiUrl>/public/core/v3/userGroups/cPYWk02I4aBeuLEvYRtaMS/addUsers
Content-Type: application/json
Accept: application/json
INFA-SESSION-ID: <sessionId>
{
"users" : ["LarryR", "ScottY"]
}

ユーザーの削除

ユーザーグループからユーザーを削除するには、次のURIのいずれかを使用してPUT要求を送信します。
/public/core/v3/userGroups/<user group ID>/removeUsers
/public/core/v3/userGroups/name/<user group name>/removeUsers
ユーザーグループから削除するユーザー名の配列を含めます。
ユーザーグループからユーザーを削除するには、次の例のような要求を送信します。
PUT <baseApiUrl>/public/core/v3/userGroups/cPYWk02I4aBeuLEvYRtaMS/removeUsers
Content-Type: application/json
Accept: application/json
INFA-SESSION-ID: <sessionId>
{
"users" : ["LarryR", "ScottY"]
}

PUT応答

成功したら成功コードを、エラーが発生したらエラーオブジェクトを返します。

ユーザーグループの削除

組織のユーザーグループを削除できます。
ユーザーグループを削除するには、次のURIを使用します。
/public/core/v3/userGroups/<user group Id>