一括削除¶
POST /api/v1/workspace/inner_accesskey/batch_delete
概要¶
ワークスペースUUIDごとに、アクティブなinner sysシステムKeyを一括削除します。
呼び出し前の確認と使用手順¶
w権限が必要です。まずワークスペースリストで各ワークスペースを確認し、次に組み込みKeyリストで対応するinner sys Keyと依存先を確認してください。リクエストのworkspaceUUIDsはワークスペースUUIDの配列である必要があり、KeyレコードのUUIDでも平文のAK/SKでもありません。対象ワークスペース内でisSystem=1、businessType=inner sys、status=0のKeyのみを論理削除し、通常のAPI Keyおよびその他のシステム業務Keyはこの操作の影響を受けません。未知のワークスペース、アクティブな組み込みKeyが存在しない場合、空配列の場合はいずれもtrueを返すことがあり、ワークスペースごとの一致件数は提供されません。現在の実装では旧AKの認証キャッシュを明示的に無効化しますが、同時に旧SKキャッシュを明示的にクリアするわけではありません。旧SKに有効な認証キャッシュが存在する場合、成功レスポンスだけで旧認証情報がすべて直ちに失効したと判断することはできません。管理者がキャッシュ処理と実際の認証結果を確認してください。削除後に初期化して組み込みKeyを取得を呼び出すとKeyが再初期化されるため、「まだ存在しない」ことの検証には使用できません。削除を検証するには、リストの照会および実際の認証情報による認証を確認してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 元のパスとリクエストボディの署名バージョン。省略したまま本ページのアルゴリズムを継続使用することはできません。 例: v20240417取得または入力方法: 本ページの例ではこの固定バージョンを使用し、例の署名アルゴリズムと組み合わせます。 |
|
| X-Df-Access-Key | string | Y | 本モジュールのリストはrまたはw権限で使用できます。その他の3項目(GET初期化を含む)にはw権限が必要です。 例: <external-access-key>取得または入力方法: サイト管理者が割り当てたExternal API AKを使用します。ワークスペースのOpenAPI Keyは使用できません。 |
| 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秒文字列を生成します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| workspaceUUIDs[*] | string | 単一のワークスペースUUIDであり、wsak_レコードUUIDではありません。 例: wksp_example001取得または入力方法: ワークスペースリストから単一のワークスペースuuidを取得します。 |
|
| workspaceUUIDs | array | Y | 必須の文字列配列。ワークスペースUUIDに基づいて削除します。nullは無効で、[]はどのKeyも削除しません。 nullを許可: False 例: ["wksp_example001"]取得または入力方法: ワークスペースリストのcontent.data[].uuidから処理対象のワークスペースを1件ずつ取得し、対応する組み込みKeyを先に確認します。 |
パラメータ補足説明¶
サイトレベルのExternal API認証情報を使用します。認証についてはExternal API 署名認証を参照してください。リストはrまたはw権限を許可し、その他の3項目(GET初期化を含む)にはw権限が必要です。すべてのレスポンスで高権限の認証情報が平文で返される可能性があるため、通常のフロントエンドページのマスク表示ルールを適用しないでください。例ではプレースホルダー値を使用しており、実際の認証情報は安全に保管する必要があります。データベースの削除状態と後続のキャッシュ処理は段階的に実行されるため、エラー時はまず削除済みの範囲を確認し、初期化/削除を繰り返して認証情報を切り替えることを避けてください。
リクエスト例¶
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/inner_accesskey/batch_delete'
query = {}
data = {'workspaceUUIDs': ['wksp_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を返します。一致がない場合や空配列の場合もtrueになる可能性があります。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
パラメータが宣言に適合しない場合は共通リクエストエラーを返します。データベース、キャッシュなどの通常の内部例外は最終的に500 ft.InternalServerErrorに統一されます。書き込みリクエストが失敗した場合は、まず永続状態とキャッシュを確認してください。すべてが未反映であることは保証されません。
| HTTP 状態 | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエストJSONの構文が無効 | リクエストJSONの形式エラー | content.reason、line、columnに従ってJSONを修正してください。 |
| 400 | ft.JsonFormatError | リクエストJSONの最上位がオブジェクトではない | 一部のJSONファイル形式エラー | 削除リクエストはJSONオブジェクトを使用し、workspaceUUIDsはその配列フィールドです。 |
| 500 | ft.InternalServerError | データベース、キャッシュの失効、または明示的に処理されていない内部例外 | 内部エラー | traceIdを保存し、まずKeyの現在の状態と実際の呼び出し結果を確認してから再試行を判断してください。データベースがすでにコミットされている可能性があるため、エラーレスポンスだけで変更がないと判断することはできません。 |