一括削除¶
POST /api/v1/workspace/accesskey/batch_delete
概要¶
UUID 配列に基づいて API キーを一括削除します。
呼び出し前の準備と使用手順¶
External 認証情報の w 権限が必要です。リクエストには workspaceUUID フィルターがないため、同一バッチ内で複数のワークスペースに一致する可能性があります。各キーのワークスペース、名前、クライアント依存関係を項目ごとに確認してから送信してください。未知、削除済み、およびシステムキーは無視されます。空配列はどのキーも削除しませんが、成功として扱われます。バッチ内のいずれかの一致キーが Agent バインド済みのソースである場合、バッチ全体が拒否され、マーク済みの他のキーは先にコミットされません。正常なフローでは、一致したキーを論理削除し、対応するロールの関連付けをクリアします。コミット後、キーごとに AK/SK の無効化キャッシュを書き込みます。キャッシュ異常により、バッチが削除された後に 500 が返される可能性があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョンです。省略したまま本ページのアルゴリズムを継続使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 本モジュールの一覧では r または w 権限を使用できます。その他のエンドポイント(GET 詳細を含む)には、w 権限の External 認証情報が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が割り当てた External API AK を使用します。ワークスペースの OpenAPI キーは使用できません。 |
| X-Df-Nonce | string | Y | 一時的なシリアル番号です。失敗して再送する場合も新しい値を生成し、署名を再計算します。 例: 97d275ee9f774315a7885ba7347acbd9取得または入力方法: リクエストごとに uuid.uuid4().hex を再生成します。 |
| X-Df-Signature | string | Y | 大文字のメソッド、nonce、元の完全なパス、timestamp、および元の UTF-8 リクエストボディをスペースで連結し、HMAC-SHA256 を実行して hex ダイジェストを取得します。 例: <hmac-sha256-hex>取得または入力方法: External API 署名認証に従い、対応する SK を使用して計算します。完全に実行可能なテンプレートは以下を参照してください。 |
| X-Df-Timestamp | string | Y | サイトに設定された署名有効時間ウィンドウ内である必要があり、例の時刻を再利用できません。 例: 1785427200取得または入力方法: 送信時に str(int(time.time())) を使用して現在の Unix 秒文字列を生成します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| akUUIDs[*] | string | 個々のキーレコードの UUID です。平文の ak/sk でもワークスペース UUID でもありません。 例: wsak_example001取得または入力方法: API キー一覧 の content.data[].uuid から個々のキーレコード UUID を取得します。 |
|
| akUUIDs | array | Y | 必須の文字列配列で、null にはできません。[] は削除を行わず、重複した UUID は同一レコードにのみ一致します。未知/削除済み/システムキーは無視されます。 null を許可: False 例: ["wsak_example001"]取得または入力方法: API キー一覧 の content.data[].uuid または API キー詳細 の content.uuid から対象を取得し、所属ワークスペースを項目ごとに確認します。 |
パラメータ補足¶
サイトレベルの External API AK/SK を使用します。署名方式はExternal API 署名認証を参照してください。本ページで生成するワークスペース API キーと External 署名認証情報は同じ認証情報セットではありません。External は現在 AK/SK の平文を返し、フロントエンド画面のマスクポリシーを適用しません。レスポンス例はすべてプレースホルダー値を使用しているため、実際のレスポンスは認証情報として保管してください。一括削除と単一削除はどちらも、削除された AK/SK を使用する後続の OpenAPI 呼び出しに影響します。代替の認証情報を事前に準備してください。
リクエスト例¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 対象サイトのアドレスおよび管理者が割り当てた External API AK/SK に置き換えます。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/workspace/accesskey/batch_delete'
query = {}
data = {'akUUIDs': ['wsak_example001']}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
レスポンス¶
HTTP 200、application/json の共通エンベロープで、ビジネス結果は content に格納されます。External は declaration を自動的に追加せず、一覧のページネーションは content.pageInfo に格納されます。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | ルートは固定で true を返し、一致件数やキーごとの結果は返しません。空配列の場合や、すべての UUID が無視された場合でも true になります。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義を参照してください。
以下の表に、確認済みのリクエストおよびビジネス分岐を示します。通常のデータベース/キャッシュ/監査 5xx はグローバルラッパーにより ft.InternalServerError になります。書き込みエンドポイントがエラーを返した場合、名前、Owner フラグ、ロール、または削除状態がすでに保存されている可能性があるため、まず現在の状態を照会してから次のステップを決定する必要があります。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではありません | 一部の JSON ファイル形式エラー | JSON オブジェクトを使用し、配列や null をリクエストボディ全体として使用しないでください。 |
| 400 | ft.AgentWorkspaceAKCanNotDelete | 一致するバッチに createdWay=agent かつアカウントにバインドされたキーが含まれています | Agent にバインドされた API キーは削除できません | 該当するキーを削除し、対応する Agent 管理入口で処理してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ無効化、監査、または未処理のフィールド例外 | 内部エラー | traceId を保持し、キーの現在の名前、ロール、状態を確認してください。データは先にコミットされてから失敗する可能性があるため、500 だけをもって未反映とみなすことはできません。 |