メンバーを招待¶
POST /api/v1/workspace/member/batch_invitation
概要¶
メールでユーザーを現在のワークスペースに一括招待し、ロールを事前に設定します。
呼び出し前の準備と使用手順¶
メールアドレスの配列、空でない roleUUIDs、method=email を用意します。API Key は OpenAPI モードで招待するため、フロントエンドの検証コードは要求されませんが、ワークスペースのメンバー上限、招待頻度、ロールの割り当て可能範囲は引き続き検証されます。ロール一覧に wsAdmin が含まれていても、現在の身分で管理者を招待できるとは限りません。この操作が可能なのは owner/wsAdmin の身分のみです。招待権限だけを持つカスタムロールでは、割り当て可能範囲がさらに制限されます。招待メールは非同期で送信されるため、受信やユーザーの参加完了を意味するものではありません。招待リンクのキャッシュ有効期間は 24 時間です。同じ応答待ちのメールアドレスを再度招待すると、古い招待は無効になります。承認待ちのメールアドレスは送信をスキップしますが、現在の waitAuditEmail には、以前は応答待ちのみで今回再送信したメールアドレスも含まれる場合があるため、これだけでは承認状態や送信の有無を判断できません。コンソールの招待記録の状態と併せて確認する必要があります。サイトが招待機能を無効にしている場合や現在のメール方式をサポートしていない場合も、インターフェースは message を付けて成功を返すことがあるため、HTTP 200 だけで判断してはいけません。メンバー関係、ロール、トークン、キャッシュなどの処理は段階的に保存される場合があります。異常やタイムアウトが発生した場合は、まずメンバーとロールの状態を読み取り、そのうえで再試行を判断してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得・入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| to[*] | string | 配列内の単一の文字列識別子。 例: xxx@guance.com取得・入力方法: 招待する人の実際のメールアドレスを入力します。例のアドレスは置き換えてください。未登録ユーザーでもかまいません。 |
|
| roleUUIDs[*] | string | 配列内の単一の文字列識別子。 例: readOnly取得・入力方法: ロール一覧の content.data[].uuid から現在のワークスペースで利用可能なロールを取得します。組み込み識別子は wsAdmin(管理者)、general(標準メンバー)、readOnly(読み取り専用メンバー)で、role_ で始まるものはカスタムロールです。 |
|
| method | string | Y | 招待方式。必須で、現在は email のみです。 null 許可: False 選択可能な値: ['email'] 例: email取得・入力方法: 現在の公開インターフェースでは固定で email を指定します。 |
| roleUUIDs | array | Y | 招待対象者全員に一律で付与するロール UUID の配列で、空にはできません。owner は指定できません。wsAdmin は owner/wsAdmin の身分で招待する場合に限ります。その他のロールには tokenRead/tokenReplace 権限を含められません。 null 許可: False 例: ["readOnly"]取得・入力方法: ロール一覧の content.data[].uuid から現在のワークスペースで利用可能なロールを取得します。組み込み識別子は wsAdmin(管理者)、general(標準メンバー)、readOnly(読み取り専用メンバー)で、role_ で始まるものはカスタムロールです。 |
| to | array | Y | 招待対象メールアドレスの配列で、必須です。送信前に空値を除去しメールアドレスを検証してください。null を渡さないでください。 null 許可: True 例: ["xxx@guance.com"]取得・入力方法: 招待する人の実際のメールアドレスを入力します。例のアドレスは置き換えてください。未登録ユーザーでもかまいません。 |
パラメータ補足説明¶
インターフェースは招待リンクやアカウント UUID を返しません。メンバーが実際に参加した後、メンバー一覧から UUID を取得します。to について null を許可するという従来の記述が存在しますが、現在の実装では走査可能なメールアドレス配列が必要なため、クライアントは例に従って配列を渡してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/member/batch_invitation' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"to":["xxx@guance.com"],"roleUUIDs":["readOnly"],"method":"email"}'
レスポンス¶
HTTP 200、application/json。以下の例は、そのまま読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.waitAuditEmail | array<string> |
現在の返却値には、過去の承認待ちまたは応答待ちの招待記録に関わるメールアドレスが含まれます。今回再送信したメールアドレスが含まれる場合もあるため、これだけで承認待ちかどうかや送信の有無を判断できません。 |
| content.waitAuditEmail[] | string | 過去の招待記録に関わる単一のメールアドレスで、これだけで承認状態や送信状態を判定できません。 |
| content.message | string | 招待が有効でない、または現在の方式がサポートされていない場合の説明です。この分岐では waitAuditEmail が返らないことがあります。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"waitAuditEmail": [],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
サイトで招待機能が有効になっていない場合は、次のように返ることがあります
{
"code": 200,
"content": {
"message": "服务未启用",
"declaration": {}
},
"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 オブジェクトを送信します。 |
| 406 | ft.InvalidEmail | to に無効なメールアドレスが含まれている | 無効なメールアドレスです | メールアドレスの形式に従って修正し、空値を除去します。 |
| 400 | ft.RoleUUIDNullError | roleUUIDs が空 | ロール uuid リストが空です | 現在のワークスペースで利用可能なロールを少なくとも 1 つ選択します。 |
| 400 | ft.RoleInvitationWsAdminPermissionError | 招待ロールに owner が含まれている | 招待メンバーのロールをオーナーにすることはできません | オーナーの移譲は専用のフローを使用し、招待では設定しません。 |
| 400 | ft.RoleInvitationPermissionError | wsAdmin 以外の対象ロールにトークンの読み取りまたは置換権限が付与されている | Token 閲覧または Token 変更権限を含むロールは招待できません | この権限を持たない招待ロールを選択し、参加後に権限付与フローで調整します。 |
| 400 | ft.MemberRoleNotFound | 対象ロールが存在しない、削除済み、または現在のワークスペースに適用されない | 指定されたメンバーロールが現在のワークスペースに見つかりません | ロール一覧から選択し直します。 |
| 403 | ft.Forbidden | 現在の招待元の身分では選択したロールを割り当てられない、または owner/wsAdmin 以外が管理者を招待している | 操作権限がありません | 適切な権限範囲を持つ身分を使用するか、自分が割り当て可能なロールを選択します。 |
| 403 | ft.ForbiddenFreeEditionLimit | ワークスペースのメンバー数が現在のプランの上限に達している | 無料版ワークスペース {} は上限( {} 個)に達したため新規作成できません。商用プランを開通すると制限が解除されます | メンバー数とワークスペースのプランを確認します。 |
| 400 | ft.InvitationEmailTooMany | 今回分と既存の送信量が現在のサイトの招待頻度制限を超えている | 招待メール数が 1 時間あたりの既定の最大値({}個)を超えています。しばらくしてから再試行してください | 一括件数を減らし、頻度ウィンドウの終了後に再試行します。既定ではワークスペースあたり 1 時間に 20 件のメールアドレスで、サイト設定で上書きできます。 |
| 404 | ft.MemberAlreadyExistsInWorkspace | 招待対象のメールアドレスが現在のワークスペースに直接関連付けられた一般メンバーである | ワークスペースにこれらのメンバーが既に存在します | リクエストから既存メンバーを削除します。ロールを調整する場合はメンバー変更を使用します。 |
| 500 | ft.InternalServerError | データ保存、関連リソース、キャッシュの処理に失敗 | 内部エラー | まずメンバーと権限の現在の状態を確認してから再試行を判断します。失敗が続く場合は traceId とマスク済みリクエストを提供してください。 |