メンバーを変更¶
POST /api/v1/workspace/member/batch_modify
概要¶
現在のワークスペースメンバーの直接ロール集合全体を変更します。単一メンバーのチームとニックネームも同時に調整できます。
呼び出し前の準備と使用手順¶
onlyModifyRoles=true はロールの一括置換に適しています。false は単一メンバー向けで、この場合は accountUUID を 1 つだけ渡し、チーム配列とニックネームはいずれも目標の完全な値で送信します。省略すると元のチームまたはニックネームがクリアされます。ロールは全体を置換するものであり、ロール配列を追加リストとして扱うことはできません。owner は対象アカウントにできず、この API で owner を付与することもできません。SAML マッピングが有効な関連 SSO アカウントでは、手動によるロール変更が拒否される場合があります。現在のコードでは請求センターの権限昇格承認が廃止されており、「承認不要ロール」を混在させる必要はありません。成功時は通常 content={} を返し、新しい承認リダイレクト用フィールドも提供しません。一部の渡したアカウントに直接のワークスペース関係がない場合でも、個別にエラーになることは保証されません。現在の API は roleUUIDs がすべて本ワークスペースに属するかも完全には検証しないため、未知または別ワークスペースの UUID を書き込み、旧ロールを置換できる可能性があります。クライアントはまず本ワークスペースのロール一覧で項目ごとに検証する必要があり、成功時の空オブジェクトは新しいロールが有効であることを証明しません。実行後は実際のロールとアクセス権限を照会する必要があります。メンバー関係、ロール、トークン、キャッシュなどの処理は段階的に保存される場合があります。例外またはタイムアウト後は、まずメンバーとロールの状態を読み取り、そのうえで再試行を判断してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| accountUUIDs[*] | string | 配列内の単一文字列識別子。 例: acnt_example取得または入力方法: ワークスペースメンバー一覧 の content.data[].uuid から、現在のワークスペースメンバーのアカウント UUID を取得します。API Key の UUID やメールアドレスではありません。 |
|
| roleUUIDs[*] | string | 配列内の単一文字列識別子。 例: readOnly取得または入力方法: ロール一覧 の content.data[].uuid から、現在のワークスペースで利用可能なロールを取得します。組み込み識別子は wsAdmin(管理者)、general(標準メンバー)、readOnly(読み取り専用メンバー)です。role_ で始まるものはカスタムロールです。 |
|
| memberGroupUUIDs[*] | string | 単一のチーム UUID。group_ で始まります。 例: group_example取得または入力方法: 本ワークスペースのチーム管理、またはワークスペースメンバー一覧 の member_group[].uuid から取得します。 |
|
| accountUUIDs | array | Y | 既存メンバーのアカウント配列。onlyModifyRoles=false の場合は、最初のアカウントのチーム/ニックネーム更新が不確定になるのを防ぐため、クライアントが 1 つのアカウントだけを送信する必要があります。null は送信しないでください。 null を許可: True 例: ["acnt_example"]取得または入力方法: ワークスペースメンバー一覧 の content.data[].uuid から、現在のワークスペースメンバーのアカウント UUID を取得します。API Key の UUID やメールアドレスではありません。 |
| acntWsNickname | string | onlyModifyRoles=false の場合に更新します。省略時はデフォルトで空文字列となり、元のニックネームをクリアできます。true の場合は無視されます。最大 128 カスタム長単位で、ASCII/半角カタカナは 1、漢字などは通常 2 として数えます。 null を許可: True $maxCustomLength: 128 例: 本番オンコールエンジニア取得または入力方法: 業務担当者がこのメンバー用に本ワークスペースのニックネームを入力します。全サイトのアカウント name ではありません。 |
|
| memberGroupUUIDs | array | onlyModifyRoles=false の場合の完全な目標チーム一覧。省略または [] は元のチームを削除します。null は送信しないでください。true の場合はチームを変更しません。 null を許可: True 例: ["group_example"]取得または入力方法: 現在のワークスペースのチーム管理、またはワークスペースメンバー一覧 の member_group[].uuid から取得します。false モードでは完全な目標配列を送信します。 |
|
| onlyModifyRoles | boolean | Y | 必須の boolean。true はチームとニックネームを保持します。false は accountUUID を 1 つだけ送信し、目標のチームとニックネームを同時に指定する必要があります。 null を許可: False 例: true取得または入力方法: ロールを一括変更する場合は true、1 メンバーのチーム/ニックネームも変更する場合は false を使用します。 |
| roleUUIDs | array | Y | 完全な目標直接ロール集合。空にできません。元の直接ロールを置換します。グループ/チーム継承ロールは対応関係に従って別途有効になります。owner を含めることは禁止です。 null を許可: False 例: ["readOnly"]取得または入力方法: ロール一覧 の content.data[].uuid から、現在のワークスペースで利用可能なロールを取得します。組み込み識別子は wsAdmin(管理者)、general(標準メンバー)、readOnly(読み取り専用メンバー)です。role_ で始まるものはカスタムロールです。 |
パラメータの補足説明¶
本公開 API には remark などの内部パラメータはありません。accountUUIDs には null を許可する過去の宣言がありますが、現在の実装では配列が必要です。false モードで空配列を渡すと内部エラーが発生する可能性があります。クライアントは例に従って非空配列を送信し、ロール一覧から利用可能な UUID を取得してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/member/batch_modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"accountUUIDs":["acnt_example"],"roleUUIDs":["general"],"onlyModifyRoles":true}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 現在の正常フローでは空オブジェクト {} を返し、declaration を付加せず、アカウントごとの更新結果も提供しません。 |
{
"code": 200,
"content": {},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーの詳細は共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではありません | 一部の JSON ファイル形式エラー | 単一の JSON オブジェクトを送信してください。 |
| 400 | ft.SSOUnsupportModifyRole | 対象の SSO アカウントのロールが、SAML マッピングが有効な ID プロバイダーによって管理されています | SAML マッピングが有効なため、SSO アカウントのロール変更は禁止されています | 対応する ID プロバイダーまたはマッピングルールで調整し、ローカルでの上書きを避けてください。 |
| 400 | ft.RoleUUIDNullError | roleUUIDs が空です | ロール UUID リストが空です | 本ワークスペースで有効なロールを少なくとも 1 つ指定してください。 |
| 400 | ft.InvalidActionSaasLimit | 対象ロール集合に owner が含まれています | 無効な操作です。SaaS ではオーナーを変更できません | オーナー移譲フローを使用してください。 |
| 400 | ft.ForbiddenModifyOwner | 対象アカウントが現在のワークスペースのオーナーです | 無効な操作です。オーナーは変更できません | owner アカウントを変更せず、オーナー移譲フローを使用してください。 |
| 404 | ft.WorkspaceNoExistsOwner | 現在のワークスペースで有効なオーナー関係が見つかりません | ワークスペースにオーナーが存在しません | まず管理者に連絡し、ワークスペースのオーナー状態を確認してください。 |
| 400 | ft.MemberRoleNotFound | 操作可能な現在のワークスペースの直接メンバー関係がありません | 現在のワークスペースで指定されたメンバーロールが見つかりません | 現在のメンバー一覧でアカウントと直接メンバーであることを確認してください。 |
| 500 | ft.InternalServerError | データ保存、関連リソース、またはキャッシュ処理に失敗しました | 内部エラー | まずメンバーと権限の現在の状態を確認し、そのうえで再試行を判断してください。継続的に失敗する場合は traceId と機密情報をマスクしたリクエストを提供してください。 |
| 404 | ft.NotFoundAccount | onlyModifyRoles=false の場合、単一メンバー監査用に選択したアカウントに有効な直接メンバー関係がありません | 指定されたアカウントが見つかりません | このモードでは有効な直接メンバー UUID を 1 つだけ送信してください。複数アカウントを重複排除した後の先頭項目が入力順を引き継ぐことは保証されません。 |