メンバーを追加¶
POST /api/v1/workspace/{workspace_uuid}/member/batch_add
概要¶
サイト内の既存アカウントをワークスペースに一括追加し、同じロールを付与します。
呼び出し前の準備と使用手順¶
w 権限の External 認証情報が必要です。まずサイトアカウントリストから既存アカウントを選択し、次にワークスペースロールリストからこのワークスペースで使用可能なロールを選択します。この API はアカウントを作成せず、アカウント作成メールも送信しません。アカウントは有効または無効の状態にできますが、無効なアカウントは正常にログインできず、このモジュールのメンバーリストにも表示されません。アカウント UUID を重複排除した後、項目ごとに検証します。無効なアカウントまたはロールが 1 つでもあれば、先にエラーを返します。すでに正常にワークスペースへ追加されている直接メンバーを再度追加すると重複として報告され、冪等な成功として扱うことはできません。空のアカウント配列または空のロール配列は、既存の検証が完了した後であれば関係を追加せずに true を直接返すことができますが、クライアントは意図しない空操作を禁止すべきです。一括追加で owner を付与することはできません。所有者を変更する場合は譲渡 API を使用してください。
パスパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 が一般的です。 |
|
| accountUUIDs | array | Y | 必須の文字列配列。重複排除後、status=0 または 2 の既存アカウントのみを受け付けます。null は不正で、[] は新規追加しません。 null を許可: False 例: ["acnt_example001"]取得または入力方法: 既存メンバーはワークスペースメンバーリストの content.data[].uuid から取得します。追加/譲渡の対象アカウントはサイトアカウントリストから取得することもできます。 |
| roleUUIDs | array | Y | 必須の文字列配列。ロールは現在のワークスペースで有効な範囲内である必要があります。複数指定できますが、owner を含めることはできません。null は不正で、[] は新規追加しません。 null を許可: False 例: ["general"]取得または入力方法: 該当ワークスペースで有効なロールの uuid はワークスペースロールリストから取得します。組み込みロールには general、readOnly、wsAdmin が一般的です。 |
パラメータ補足説明¶
認証についてはExternal API 署名認証を参照してください。本ページの例では v20240417 を使用し、元の完全パス、Query、リクエストボディの署名アルゴリズムに対応しています。このモジュールは指定ワークスペースのメンバー関係またはロールを操作し、アカウント自体は作成しません。書き込みリクエストが失敗した場合は、まずメンバーとロールの現状を確認してから再試行を判断してください。この操作は直接メンバーとロールの関連付けを追加し、既存の招待レコードを更新します。成功時にアカウントごとのステータスは返されないため、失敗後は項目ごとに確認してください。
リクエスト例¶
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_add'
query = {}
data = {'accountUUIDs': ['acnt_example001'], 'roleUUIDs': ['general']}
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 | boolean | 成功時は true で、新規追加件数ではありません。空操作でも true になる場合があります。 |
{
"code": 200,
"content": true,
"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.InvalidAccountUUID | 重複排除後のアカウントリストに、存在しない、削除済み、または status が 0/2 以外のアカウントが含まれる | 無効なアカウント UUID: {} | サイトアカウントリストから有効な uuid を再選択します。 |
| 400 | ft.InvalidRoleUUID | roleUUIDs に現在のワークスペースで有効な範囲にないロールが含まれる | 無効なロール UUID: {} | 該当ワークスペースのロールリストから返された有効な uuid を使用します。 |
| 400 | ft.ForbiddenBatchAddOwner | 実際の追加リクエストで roleUUIDs に owner が含まれる | 無効な操作です。所有者を一括追加することはできません | 通常のロールを使用してメンバーを追加し、Owner の変更が必要な場合は譲渡 API を使用します。 |
| 404 | ft.MemberAlreadyExistsInWorkspace | アカウントの status=0 かつ、このワークスペースのアクティブな直接メンバー関連付けがすでに存在する | ワークスペースにこれらのメンバーがすでに存在します | まず既存メンバーを確認します。ロールの更新には一括変更を使用し、重複追加しないでください。 |
| 401 | ft.WKSPNotExistOrReleased | 実際に追加対象の関係があるときに、ワークスペースが存在しない、またはアクティブ状態でない | ワークスペースが存在しない/またはすでに解放されています | ワークスペースリストからアクティブなワークスペースを選択します。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、旧承認タスクのキャンセル、または未処理の配列/フィールド例外 | 内部エラー | traceId を保存し、管理者に実際の関係とキャッシュを確認してもらいます。書き込み操作は部分的にコミット済みの可能性があるため、盲目的に再送しないでください。 |