取得¶
GET /api/v1/workspace/member_group/get
概要¶
指定したチームとその選択済みメンバー、選択可能なメンバー、ロールを取得します。または、新規作成時のメンバー候補を取得します。
呼び出し前の準備と使用手順¶
Query の groupUUID はチーム一覧から取得します。有効な UUID を渡すと、チームエンティティ、groupMembers、membersNotInGroup、roleInfos を返します。省略するか空文字列を指定した場合は、新規作成用の候補構造を返します。エンティティの uuid、名前などのフィールドは含まれず、現在有効なすべてのメンバーは membersNotInGroup に含まれます。既存でも無効化された、またはワークスペースから離脱したメンバーは、選択可能なメンバー情報として返されません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| groupUUID | string | 任意のチーム UUID。省略または空文字列の場合、すべての選択可能なメンバーを取得します。 例: group_example取得または入力方法: チーム一覧 の content[].uuid からチーム UUID を取得します。新しいチームでメンバーを準備する場合は省略できます。 |
パラメータ補足説明¶
変更時は groupMembers[].uuid から accountUUIDs を構築してください。roleInfos[].uuid から返されたロールを取得します。ロールサマリーには、メンバーが空のチームに既存のロールが含まれない場合があるため、変更前に別途確認し、[] で誤ってクリアしないようにしてください。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/workspace/member_group/get' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode groupUUID=group_example
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | チーム詳細または新規作成候補。エンティティ列は、有効な groupUUID を指定した場合にのみ存在します。 |
| content.id | integer | データベースレコード番号。操作には uuid を使用します。 |
| content.uuid | string | チーム UUID。 |
| content.name | string | チーム名。 |
| content.workspaceUUID | string | 所属ワークスペース UUID。 |
| content.status | integer | アクティブなチームは 0 です。 |
| content.creator | string | 作成者。 |
| content.updator | string | 更新者。空の場合があります。 |
| content.createAt | integer | 作成日時(Unix 秒)。 |
| content.updateAt | integer | エンティティの更新日時(Unix 秒)。未更新の場合は -1。現在の変更ではこのフィールドが更新される保証はなく、メンバー/ロールが変更されたかどうかの判断には使用できません。 |
| content.deleteAt | integer | 削除日時(Unix 秒)。未削除の場合は -1。 |
| content.groupMembers | array<object> |
チーム内でまだ有効なメンバー。関連付けの作成日時の降順で並びます。 |
| content.membersNotInGroup | array<object> |
このワークスペースの有効なメンバーのうち、まだこのチームに参加していない候補。 |
| content.roleInfos | array<object> |
ロールサマリー。現在メンバーが空のチームでは空で表示される場合があり、これに基づいてロールが未設定と推測することはできません。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
| content.groupMembers[].uuid | string | メンバーアカウント UUID。 |
| content.groupMembers[].name | string | アカウント表示名。 |
| content.groupMembers[].email | string | アカウントのメールアドレス。 |
| content.groupMembers[].acntWsNickname | string | このワークスペースでのニックネーム。未設定の場合は空文字列。 |
| content.membersNotInGroup[].uuid | string | メンバーアカウント UUID。 |
| content.membersNotInGroup[].name | string | アカウント表示名。 |
| content.membersNotInGroup[].email | string | アカウントのメールアドレス。 |
| content.membersNotInGroup[].acntWsNickname | string | このワークスペースでのニックネーム。未設定の場合は空文字列。 |
| content.roleInfos[].uuid | string | ロール UUID または組み込みロール識別子。roleUUIDs の要素として使用できます。 |
| content.roleInfos[].name | string | ロール表示名。 |
{
"code": 200,
"content": {
"id": 42,
"uuid": "group_example",
"name": "本番運用",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"groupMembers": [
{
"uuid": "acnt_example",
"name": "運用メンバー",
"email": "xxx@guance.com",
"acntWsNickname": ""
}
],
"membersNotInGroup": [],
"roleInfos": [
{
"uuid": "role_example",
"name": "運用読み取り専用"
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
新規チーム候補の呼び出し(groupUUID なし)
{
"code": 200,
"content": {
"groupMembers": [],
"membersNotInGroup": [
{
"uuid": "acnt_example",
"name": "運用メンバー",
"email": "xxx@guance.com",
"acntWsNickname": ""
}
],
"roleInfos": [],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 宣言されていない Query パラメータを使用した、またはパラメータがルールに違反している | パラメータの解析に失敗しました | Query パラメータ表と例を確認してください。 |
| 404 | ft.MemberGroupNoExists | 対象チームが存在しない、削除済み、またはこのワークスペースにない | チームが存在しません | チーム一覧 からアクティブなチームの UUID を再コピーしてください。 |
| 500 | ft.InternalServerError | チームまたはメンバー情報の読み取りに失敗しました | 内部エラー | UUID を確認し、traceId を保持してサポートに連絡してください。 |