メンバーの個人 API Key の一括有効化・無効化¶
POST /api/v1/workspace/member/personal_api_key/enable/modify
概要¶
メンバーが現在のワークスペースで個人 API Key を使用する機能を一括で有効または無効にします。
呼び出し前の準備と使用手順¶
ワークスペースメンバーリストからメンバー UUID を取得し、空でない accountUUIDs と 0/1 のスイッチを送信します。アカウントは重複排除され、空の値は無視されます。対象は、現在のワークスペースで直接または継承したロールを持つ有効なメンバーである必要があります。owner は無効化できません。メンバーのスイッチを保存し、既存のユーザーおよびエージェントの個人 Key レコードを同期的に有効化/無効化し、対応する認証キャッシュをクリアします。有効化ではキーを作成または返却しません。削除済みのキーがこれによって再作成されることもありません。返却される updated は、今回重複排除後の対象メンバー数であり、実際に状態が変化した Key 数ではありません。その後、メンバーリストの enablePersonalAPIKey を照会してスイッチを確認します。実際に使用するには、メンバーのロールと API 権限も満たす必要があります。メンバーシップ、ロール、トークン、キャッシュなどの処理は段階的に保存される場合があります。異常またはタイムアウト後は、まずメンバーとロールの状態を読み取り、そのうえで再試行を判断してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| accountUUIDs[*] | string | 配列内の単一文字列識別子。 例: acnt_example取得または入力方法: ワークスペースメンバーリストの content.data[].uuid から現在のワークスペースメンバーのアカウント UUID を取得します。API Key の UUID やメールアドレスではありません。 |
|
| accountUUIDs | array | Y | 対象アカウント UUID 配列。同一ワークスペースの実際のメンバーを指定し、空でない文字列を使用します。 null を許可: False 例: ["acnt_example"]取得または入力方法: ワークスペースメンバーリストの content.data[].uuid から現在のワークスペースメンバーのアカウント UUID を取得します。API Key の UUID やメールアドレスではありません。 |
| enablePersonalAPIKey | integer | Y | 必須の整数。0 または 1 のみを許可します。JSON のブール値や文字列ではありません。 null を許可: False 選択可能な値: [0, 1] 例: 0取得または入力方法: 対象メンバーに本ワークスペースの個人 Key の使用を禁止する場合は 0、許可する場合は 1 を入力します。 |
パラメータ補足説明¶
現在公開されているパラメータ宣言の整数 0/1 を使用します。コントローラーが互換性のために受け付ける他の型は、公開された呼び出し形式ではありません。この API はキーの内容を一切返却しません。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/member/personal_api_key/enable/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"accountUUIDs":["acnt_example"],"enablePersonalAPIKey":0}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.updated | integer | 今回処理された重複排除後の空でないメンバー数。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"updated": 1,
"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.MissingParameters | アカウント配列が空、またはスイッチフィールドが欠落 | パラメータ欠落 | 少なくとも 1 つのメンバー UUID を送信し、enablePersonalAPIKey を指定してください。 |
| 404 | ft.NotFoundAccount | アカウントが存在しない、状態が要件を満たさない、または本ワークスペースの有効なロールが見つからない | 指定されたアカウントが見つかりません | 現在のワークスペースのメンバーリストからアカウントを再取得し、直接ロールおよび継承ロールを確認してください。 |
| 403 | ft.Forbidden | owner の個人 API Key を無効化しようとした | 操作権限がありません | owner のスイッチを維持し、他のメンバーを調整してください。 |
| 500 | ft.InternalServerError | データ保存、関連リソース、またはキャッシュ処理に失敗 | 内部エラー | まずメンバーと権限の現在の状態を確認してから再試行を判断してください。継続的に失敗する場合は traceId とマスク済みリクエストを提供してください。 |