コンテンツにスキップ

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

フィードバック

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