変更¶
POST /api/v1/workspace/{workspace_uuid}/member/batch_modify
概要¶
ワークスペースメンバーの直接ロールを一括で置き換えます。
呼び出し前の準備と使用手順¶
w 権限の External 認証情報が必要です。まずワークスペースメンバー一覧を使用して、対象メンバーの現在の直接ロールと継承ロールを保存し、完全な対象リストに従って roleUUIDs を送信してください。onlyModifyRoles=true を推奨します。現在の External 呼び出しはフロントエンドのメンバー編集分岐とは異なり、memberGroupUUIDs と acntWsNickname はチーム/ニックネームに書き込まれません。現在の Owner を変更対象に指定することはできません。単一の他の直接メンバーには owner を付与できますが、その場合、他の対象ロールは破棄され、元の Owner は wsAdmin に降格され、ワークスペースメンバー関係は保持されます。複数人への Owner 設定は拒否されます。元の Owner の直接メンバー関係を削除する場合は、オーナーの移譲を使用してください。レスポンスは空のオブジェクトで、アカウントごとの成功リストは返されず、対象ロールが有効であることも保証されません。事前に本ワークスペースのロール一覧を使用して roleUUIDs の各項目を検証する必要があります。本 API が未知のロールや他ワークスペースのロールを拒否することは期待できません。これらの値は関連付けに書き込まれ、元の直接ロールを置き換える可能性があります。未知のアカウント UUID や直接メンバーでないアカウント UUID はフィルタリングされる可能性があります。古い承認レコードはキャンセルされる可能性があり、権限とキャッシュの処理はサービス間でアトミックな操作ではありません。失敗した場合は、まず現在の直接ロールを確認してから再試行してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| workspace_uuid | string | Y | 対象ワークスペース UUID。まずアクティブ状態とサイトを確認します。 例: wksp_example001取得または入力方法: ワークスペース一覧 の content.data[].uuid から取得し、ワークスペース名を確認します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョン。省略したうえで本ページのアルゴリズムを引き続き使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用しており、例の署名アルゴリズムと対応しています。 |
|
| X-Df-Access-Key | string | Y | 読み取り API では r または w 権限の認証情報を使用できますが、書き込み API には w 権限の認証情報が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が割り当てた External API AK を使用します。ワークスペースの OpenAPI Key は使用できません。 |
| X-Df-Nonce | string | Y | 一時的なシリアル番号。失敗して再送する場合も新しい値を生成し、署名を再計算します。 例: 97d275ee9f774315a7885ba7347acbd9取得または入力方法: リクエストごとに uuid.uuid4().hex を再生成します。 |
| X-Df-Signature | string | Y | 大文字のメソッド、nonce、元の完全なパス、timestamp、および元の UTF-8 リクエストボディをスペースで連結し、HMAC-SHA256 で計算した hex ダイジェスト。 例: <hmac-sha256-hex>取得または入力方法: External API 署名認証 に従い、対応する SK を使用して計算します。完全な実行可能テンプレートは以下を参照してください。 |
| X-Df-Timestamp | string | Y | サイト設定の署名有効時間枠内である必要があり、例の時刻を再利用することはできません。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) を使用して現在の Unix 秒文字列を生成します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| accountUUIDs[*] | string | 単一アカウント UUID。メールアドレス、アカウント名、ワークスペース UUID は入力できません。 例: acnt_example001取得または入力方法: ワークスペースメンバー一覧 の content.data[].uuid から既存メンバーを取得します。追加/移譲の場合は、サイトアカウント一覧 から対象アカウントを取得することもできます。 |
|
| roleUUIDs[*] | string | 単一の有効なロール UUID。組み込みロールは実際の識別子を、カスタムロールは返された uuid を使用します。 例: general取得または入力方法: ワークスペースロール一覧 から該当ワークスペースで有効なロールの uuid を取得します。組み込みロールには general、readOnly、wsAdmin が一般的です。 |
|
| memberGroupUUIDs[*] | string | 単一のチーム UUID。監査準備にのみ関与する可能性があり、本 External エントリポイント経由でチーム変更が保存されることはありません。 例: group_example001取得または入力方法: 現在は適用されません。互換性のために指定する場合は、チーム一覧から実際の uuid を取得してください。 |
|
| accountUUIDs | array | Y | 必須配列。現在の実装では直接関係のあるアカウントのサブセットが使用され、直接関係のない UUID が混在している場合は無視されることがあります。すべて一致しない場合は失敗します。null を許可すると宣言されていますが、実装では set(null) により 500 が返されます。null を渡さないでください。空配列を onlyModifyRoles=false と組み合わせた場合も、先頭要素へのアクセスにより失敗します。 null を許可: True 例: ["acnt_example001"]取得または入力方法: ワークスペースメンバー一覧 から、有効な直接メンバー関連付けがあるアカウントを選択します。 |
| acntWsNickname | string | 省略可能な文字列または null。カスタム長の上限は 128 と宣言されています(半角は通常 1、その他の文字は通常 2)。現在の External ではこのフィールドは保存されないため、省略を推奨します。 null を許可: True $maxCustomLength: 128 例: 示例空间昵称取得または入力方法: この External エントリポイントでは現在ワークスペースのニックネームを書き込みません。変更が必要な場合は、この機能をサポートするメンバー管理エントリポイントを使用してください。 |
|
| memberGroupUUIDs | array | 省略可能な配列または null。現在はメンバーのチームには適用されません。省略を推奨します。onlyModifyRoles=false の場合は監査準備に関与し、null は内部例外を引き起こす可能性があります。 null を許可: True 例: []取得または入力方法: この External エントリポイントでは現在チーム関係を書き込みません。チームメンバーを管理する必要がある場合は、対応するチーム管理機能を使用してください。 |
|
| onlyModifyRoles | boolean | Y | 必須のブール値。現在の External は非フロントエンド分岐を通るため、false でもチームやワークスペースのニックネームは書き込まれません。false の場合はさらに、単一メンバーの監査を事前に準備し、重複排除後の先頭対象が有効であることに依存します。重複排除にはセットが使用され、順序は保証されないため、先頭項目が入力配列の最初の項目とは限らず、失敗条件が増える可能性があります。 null を許可: False 例: true取得または入力方法: この External エントリポイントでは true に固定し、ロールのみを変更することを推奨します。 |
| roleUUIDs | array | Y | 必須の完全な対象ロール配列。各対象メンバーの直接ロールを置き換え、古いロールとはマージされません。チーム/バックエンドグループから継承したロールも削除されません。null または空配列にはできません。現在の実装ではロールの存在性と所属ワークスペースを項目ごとに検証しません。未知の UUID や他ワークスペースの UUID は関連付けに書き込まれても有効な権限を形成できない可能性があります。事前に本ワークスペースのロール一覧と照合して各項目を検証してください。 null を許可: False 例: ["readOnly"]取得または入力方法: ワークスペースロール一覧 から該当ワークスペースで有効なロールの uuid を取得します。組み込みロールには general、readOnly、wsAdmin が一般的です。 |
パラメータ補足説明¶
認証については External API 署名認証 を参照してください。本ページの例では v20240417 を使用しており、元の完全なパス、Query、リクエストボディの署名アルゴリズムと対応しています。このモジュールは指定ワークスペースのメンバー関係またはロールを操作するもので、アカウント自体は作成しません。書き込みリクエストが失敗した場合は、まずメンバーとロールの現状を確認してから再試行を判断してください。ロール一覧から有効な UUID を使用し、未知のカスタムロールが完全に拒否されることを前提にしないでください。書き込み後は、実際に利用可能な権限を確認してください。
リクエスト例¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 対象サイトのアドレスと、管理者が割り当てた External API AK/SK に置き換えます。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/workspace/wksp_example001/member/batch_modify'
query = {}
data = {'accountUUIDs': ['acnt_example001'], 'roleUUIDs': ['readOnly'], 'onlyModifyRoles': True}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
レスポンス¶
HTTP 200、application/json の統一エンベロープで、業務データは content にあります。External は declaration を自動追加せず、リストのページネーションは content.pageInfo を維持します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | この External 分岐が成功すると {} を返します。フロントエンド承認分岐の autoLoginUrl、needOwnerAudit、またはアカウントごとの結果は返しません。 |
{
"code": 200,
"content": {},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては 共通エラー定義 を参照してください。
以下の表は、確認済みの業務エラーおよびリクエストエラーです。通常のデータベース/ダウンストリームの 5xx または未処理例外は、グローバルで ft.InternalServerError にラップされます。書き込みリクエストの失敗は部分的な反映がないことを保証しないため、まず関係の現状を確認する必要があります。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトではありません | 一部の json ファイルの形式エラー | JSON オブジェクトを送信してください。配列や null をリクエストボディ全体として使用しないでください。 |
| 400 | ft.SSOUnsupportModifyRole | 対象 SSO アカウントの名前空間に、本ワークスペースで有効な SAML ロールマッピングが存在します | SAML マッピングが有効なため、SSO アカウントのロールは変更できません | 対応する ID プロバイダーのロールマッピングで調整するか、管理者がマッピングポリシーを確認してください。 |
| 400 | ft.RoleUUIDNullError | roleUUIDs が空配列です | ロール uuid リストが空です | 少なくとも 1 つの対象ロールを指定してください。 |
| 400 | ft.ForbiddenBatchModifyOwner | 重複排除後の複数の対象アカウントが同時に owner ロールを要求しています | 無効な操作です。オーナーを一括変更することはできません | Owner は一度に 1 つの対象にのみ変更できます。明確な移譲フローを使用してください。 |
| 400 | ft.ForbiddenModifyOwner | 変更対象に現在の Owner アカウントが含まれています | 無効な操作です。オーナーを変更することはできません | 現在の Owner をバッチから除外してください。移譲には専用 API を使用してください。 |
| 400 | ft.MemberRoleNotFound | 対象に有効な直接メンバー関連付けがありません | 現在のワークスペースで指定されたメンバーロールが見つかりません | まず追加 API を使用して直接関係を確立してください。バックエンドグループから継承したメンバーは直接メンバーとは異なります。 |
| 400 | ft.AgentMemberCanNotBeOwner | Owner を付与する有効な対象が agent 由来のメンバーです | agent 由来のメンバーをワークスペースのオーナーに設定することはできません | 通常のメンバーアカウントを Owner として選択してください。 |
| 404 | ft.NotFoundAccount | onlyModifyRoles=false の場合、監査準備で使用される重複排除後の先頭アカウントに有効な直接メンバー関係がありません。セットによる重複排除の順序は保証されません | 指定されたアカウントが見つかりません | onlyModifyRoles=true を使用し、有効な直接メンバーを選択してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、古い承認タスクのキャンセル、または未処理の配列/フィールド例外。accountUUIDs=null、あるいは onlyModifyRoles=false で対象配列が空/監査入力が異常 | 内部エラー | traceId を保存し、管理者に実際の関係とキャッシュを確認してもらってください。書き込み操作は部分的にコミットされている可能性があるため、無闇に再実行しないでください。 |