コンテンツにスキップ

メンバーを追加(デプロイメントプラン)



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 とマスク済みのリクエストを提供してください。

フィードバック

このページは役に立ちましたか?