メンバーを追加(デプロイメントプラン)¶
POST /api/v1/workspace/member/batch_add
概要¶
デプロイメントプランでは、サイトに既存のアカウントを現在のワークスペースに一括追加し、ロールを付与します。
呼び出し前の準備と使用手順¶
この API はデプロイメントプランのみをサポートし、SaaS から呼び出すと拒否されます。まず、既に存在するが本ワークスペースにまだ直接追加されていないアカウント、および本ワークスペースで利用可能なロールを準備します。すべての対象アカウントには同じロール配列が使用され、招待メールは送信されません。アカウントまたはロールに無効な値がある場合は先にエラーになります。既に直接追加済みのメンバーが含まれる場合も拒否され、冪等な権限更新 API としては機能しません。アカウントまたはロールの配列が空の場合は true を直接返すことがありますが、実際の追加が完了したことを意味するものではありません。すべての操作は現在の DF-API-KEY が属するワークスペースを対象とします。ワークスペースをまたぐ場合は、対応する Key とサイトの Endpoint を変更してください。メンバー関係、ロール、トークン、キャッシュなどの処理は段階的に保存される場合があります。例外やタイムアウトの発生後は、まずメンバーおよびロールの状態を確認してから、リトライを判断してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報です。 例: <DF-API-KEY>取得・入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| accountUUIDs[*] | string | 配列内の単一文字列識別子です。 例: acnt_example取得・入力方法: デプロイメントプランのみ:まずサイトのアカウント管理で、本ワークスペースにまだ追加されていないアカウントを作成または検索し、acnt_ UUID を取得します。本 API はサイトアカウントを作成しません。 |
|
| roleUUIDs[*] | string | 配列内の単一文字列識別子です。 例: readOnly取得・入力方法: ロール一覧 の content.data[].uuid から、現在のワークスペースで利用可能なロールを取得します。組み込み識別子は wsAdmin(管理者)、general(標準メンバー)、readOnly(読み取り専用メンバー)です。role_ で始まるものはカスタムロールです。 |
|
| accountUUIDs | array | Y | 本ワークスペースに追加する、サイトに既存のアカウントの UUID 配列です。自動的に重複が排除され、現在の呼び出し元と同一の識別子はスキップされます。 null 許可: False 例: ["acnt_example"]取得・入力方法: デプロイメントプランのみ:まずサイトのアカウント管理で、本ワークスペースにまだ追加されていないアカウントを作成または検索し、acnt_ UUID を取得します。本 API はサイトアカウントを作成しません。 |
| roleUUIDs | array | Y | 各新規メンバーに一律で付与するロール UUID 配列です。owner を含めることはできません。少なくとも 1 つの有効なロールを推奨します。 null 許可: False 例: ["readOnly"]取得・入力方法: ロール一覧 の content.data[].uuid から、現在のワークスペースで利用可能なロールを取得します。組み込み識別子は wsAdmin(管理者)、general(標準メンバー)、readOnly(読み取り専用メンバー)です。role_ で始まるものはカスタムロールです。 |
パラメータの補足説明¶
同じサイトアカウントは、ワークスペースごとに異なるロールを持つことができます。この API はアカウントごとの結果を返さないため、成功後はメンバー一覧で確認してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/member/batch_add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"accountUUIDs":["acnt_example"],"roleUUIDs":["readOnly"]}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 追加処理は true を返します。空配列、または追加対象が有効に存在しない場合も true になり得ます。 |
{
"code": 200,
"content": true,
"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.OnlySupportPaasVersion | SaaS サイトでこのデプロイメントプラン向け API を呼び出した | paas バージョンのみをサポート | SaaS ではメール招待またはコンソールの認可フローを使用してください。 |
| 400 | ft.InvalidAccountUUID | アカウント UUID がサイトに存在しない、または状態が要件を満たさない | 無効なアカウント UUID: {} | サイトのアカウント管理から有効なアカウント UUID を取得し直してください。 |
| 400 | ft.InvalidRoleUUID | roleUUIDs に現在のワークスペースで利用できない、または削除済みのロールが含まれる | 無効なロール UUID: {} | ロール一覧を読み直し、有効な UUID を使用してください。 |
| 400 | ft.ForbiddenBatchAddOwner | ロール配列に owner が含まれる | 無効な操作です。所有者を一括追加することはできません | 所有者の移譲には専用のフローを使用してください。 |
| 404 | ft.MemberAlreadyExistsInWorkspace | いずれかの対象アカウントが既に本ワークスペースに直接追加されている | ワークスペースにこれらのメンバーが既に存在します | 既存メンバーを削除し、ロールを変更する必要がある場合はメンバー変更を使用してください。 |
| 401 | ft.WKSPNotExistOrReleased | 現在のワークスペースが削除または解放されている | ワークスペースが存在しない、または既に解放されています | Key とワークスペースの状態を確認してください。 |
| 500 | ft.InternalServerError | データ保存、関連リソース、キャッシュの処理に失敗 | 内部エラー | まずメンバーと権限の現在の状態を確認してからリトライを判断してください。継続的に失敗する場合は traceId とマスク済みのリクエストを提供してください。 |