削除¶
POST /api/v1/workspace/{workspace_uuid}/delete
概要¶
ワークスペースを削除済みとしてマークし、書き込みをロックして、遅延クリーンアップフローに移行します。
呼び出し前の確認と使用手順¶
まずワークスペース一覧でワークスペース名と UUID を確認し、バックアップ、収集エンドポイントの切り替え、メンバーへの影響を確認してください。本 API はリクエストボディを必要としません。呼び出すと直ちに削除済みとしてマークされてロックされ、関連する Token とデフォルトワークスペース参照がクリーンアップされ、データ権限のクリーンアップ、ワークスペースタスクの一時停止、通知の送信が非同期で実行されます。業務データは後続の遅延クリーンアップタスクによって削除されます。リポジトリのデフォルトは 7 日ですが、実際はサイトの clearDataSet とタスクの実行時間に依存します。猶予期間をバックアップと見なすことはできません。復元が必要な場合は、クリーンアップ前に管理者に連絡して復元フローに従ってください。本 API は復元を担当しません。削除済みのワークスペースを再度削除すると「未検出」が返され、冪等な成功にはなりません。
パスパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| workspace_uuid | string | Y | 対象ワークスペースの UUID。アカウントの UUID でも収集 Token でもありません。 例: wksp_example001取得・入力方法: ワークスペース一覧の content.data[].uuid、または作成成功時の content.wsInfo.uuid から取得し、サイトとワークスペース名を確認してください。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| X-Df-SVersion | string | 例と一致させる必要があり、省略したままこのアルゴリズムを使い続けることはできません。 例: v20240417取得・入力方法: 本ページの元のパスおよびリクエストボディの署名アルゴリズムに合わせて入力してください。 |
|
| X-Df-Access-Key | string | Y | ここに示す 7 項目はすべて書き込み操作であり、External の書き込み権限が必要です。 例: <external-access-key>取得・入力方法: サイト管理者が w 権限を付与した 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>取得・入力方法: 対応する SK を使用し、External API 署名認証および下記の Python テンプレートに従って計算します。 |
| X-Df-Timestamp | string | Y | 例の固定時刻を再利用できません。サイトの署名有効ウィンドウ内である必要があります。 例: 1785427200取得・入力方法: 送信時に str(int(time.time())) で現在の Unix 秒を生成します。 |
パラメータの補足説明¶
w 権限を持つサイトレベルの External API 資格情報を使用してください。認証方法はExternal API 署名認証を参照してください。例は v20240417 に従って署名を計算しており、署名と送信には同一のパス、Query、元のリクエストボディを使用します。すべての例はデモ用の値であり、実行前に実際の対象に置き換えてください。書き込みリクエストがタイムアウトまたは 500 を返した場合は、まず現状を照会し、確認したうえで再試行するかどうかを決めてください。返却されるのはマーク後のワークスペーススナップショットであり、すべてのバックグラウンドクリーンアップが完了したことを意味しません。ライフサイクルロックやダウンストリームの状態が異常な場合、ワークスペースは既に削除マーク済みでも後続の通知が未完了の可能性があるため、現状に応じて復元または補償する必要があります。
リクエスト例¶
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/wksp_example001/delete'
query = {}
data = None
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 を自動注入しません。ワークスペースオブジェクト内の declaration はワークスペース自身が保存するフィールドです。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer | サイト内のレコード連番。以降の呼び出しでは uuid を使用します。 |
| content.uuid | string | ワークスペースの UUID。 |
| content.status | integer | 0 は正常、3 は削除済みマーク。削除時の返却スナップショットは 3 です。 |
| content.creator | string | 作成者の識別子。External による作成は通常 sys です。 |
| content.updator | string | 最終更新者の識別子。未更新の場合は空になることがあります。 |
| content.createAt | integer | 作成時刻(Unix 秒)。 |
| content.deleteAt | integer | 削除時刻(Unix 秒)。未削除の場合は通常 -1 です。 |
| content.updateAt | integer | 更新時刻(Unix 秒)。未更新の場合は通常 -1 です。 |
| content.name | string | ワークスペースの表示名。 |
| content.token | string | ワークスペースのデフォルト収集 Token。資格情報として保存され、External AK/SK として使用できません。例はプレースホルダー値を使用しています。 |
| content.cliToken | string | ワークスペースの CLI 資格情報。資格情報として保存されます。例には実際の値は含まれていません。 |
| content.dbUUID | string | メトリクスデータベースレコードの UUID。 |
| content.esInstanceUUID | string | 実際のログストレージインスタンスの UUID。 |
| content.dashboardUUID | string | ワークスペースのデフォルトビュー識別子。未設定の場合は空です。 |
| content.exterId | string | 外部システムのワークスペース識別子。通常は空で、本ページで書き込み可能なフィールドではありません。 |
| content.rpName | string | メトリクス保持ポリシーの内部別名。durationSet.rp の代替として使用しないでください。 |
| content.desc | string | ワークスペースの説明。 |
| content.durationSet | object または null | データタイプごとに保存される標準保存期間。キーはエンジン、バージョン、インデックス統合状態によって変化し、値は例えば 7d です。 |
| content.storagePolicy | object または null | データタイプごとに保存される長期ストレージポリシー。ここでの長期ポリシーは標準の durationSet と区別されます。 |
| content.datastore | object または null | データタイプごとに保存される実際のストレージエンジン(例: metric=guancedb、logging=doris)。 |
| content.lastDqlDataCheckTime | object または null | データタイプごとに記録される最新の DQL データチェック情報。システムが保守する動的オブジェクトです。 |
| content.declaration | object または null | ワークスペース自身の組織および業務の宣言。organization、business を含むことができます。これはワークスペースのカラムであり、External の汎用レスポンスに自動注入されるフィールドではありません。 |
| content.esIndexSettings | object または null | データタイプごとに保存されるインデックス設定オブジェクト。空オブジェクトはワークスペースレベルのカスタムテンプレートがないことを示し、ダウンストリームにデフォルトテンプレートがないことを意味しません。 |
| content.bindInfo | object または null | ワークスペースのブランド文言、メール、ドメインの上書きオブジェクト。キーの定義はバインド情報の設定を参照してください。 |
| content.versionType | string | ワークスペースのバージョン(例: free、freeEdition、pay、enterprise、unlimited)。作成時はサイト設定の値が採用され、本 API はバージョンの入力パラメータを提供しません。 |
| content.billingState | string | 課金状態の識別子(例: free、normal、arrearage、expired、unlimited)。 |
| content.bossStation | string | 請求センターのノード識別子(例: CN、SG、または空文字列)。 |
| content.brandKey | string | ワークスペースのブランド識別子。 |
| content.enablePublicDataway | integer | 公共 Dataway を許可するか。1 は有効、0 は無効。 |
| content.isOpenLogMultipleIndex | integer または boolean | ログのマルチインデックスを新規作成できるか。1 は有効、0 は無効。既存のインデックスはこれによって削除されません。 |
| content.esIndexMerged | integer | インデックスを統合するか。1 は統合、0 は分割。 |
| content.supportJsonMessage | integer | JSON メッセージのサポートフラグ。1 は有効、0 は無効。 |
| content.isLocked | integer | ワークスペースのロックフラグ。1 はロック、0 は未ロック。 |
| content.lockMode | string | ロックモード(例: none、writeLocked)。 |
| content.lockAt | integer | ロック時刻(Unix 秒)。未設定の場合は通常 -1 です。 |
| content.delayDeleteAt | integer | 遅延クリーンアップの計時ポイント(Unix 秒)。クリーンアップ待ちフローでない場合は通常 -1 です。 |
| content.inviteAudit | integer | メンバー招待の審査を有効にするか。1 は有効、0 は無効。 |
| content.makeResourceExceptionCode | string | リソース初期化の問題フラグ。空の場合があります。作成フローでは content のトップレベルでも最新の問題フラグを返します。 |
| content.loggingCutSize | integer | 巨大ログの分割単位(バイト)。 |
| content.language | string | ワークスペースの言語識別子。 |
| content.noviceGuide | boolean | 初心者ガイドのフラグ。 |
| content.timezone | string | ワークスペースのタイムゾーン。未設定の場合は空です。 |
| content.menuStyle | string | メニュースタイルの識別子。未設定の場合は空です。 |
| content.tenantId | integer | ワークスペースのテナント ID。作成レスポンスはテナント ID の生成前にスナップショットを取得するため -1 になることがあり、最終値は後続で詳細から読み取ってください。 |
| content.isOpenCustomMappingRule | integer | カスタムマッピングルールのスイッチ。1 は有効、0 は無効。 |
| content.enableRumMultipleTable | integer | RUM のテーブル分割スイッチ。1 は有効、0 は無効。 |
| content.enableMFA | boolean | MFA を要求するか。 |
| content.disableQueryAcceleration | integer | クエリ高速化の無効化フラグ。1 は無効化、0 は無効化しない。 |
| content.disableDataWrite | integer | 書き込みの無効化フラグ。1 は無効化、0 は無効化しない。 |
| content.disableDataWriteAt | integer | 書き込み無効化時刻(Unix 秒)。未設定の場合は通常 -1 です。 |
| content.logBackupQueryTimeLimit | integer | バックアップログのクエリ可能期間の制限値(時間単位)。 |
| content.engineSetting | object | エンジン専用設定の動的オブジェクト。履歴上の nodegroup フィールドは出力時に node_group に正規化されます。 |
| content.enableAI | boolean | ワークスペースの AI マスタースイッチ。 |
| content.enableAPIKeySecurityDisplayPolicy | boolean | API Key セキュア表示ポリシーのスイッチ。 |
| content.enableObsyAISubscriptionBilling | boolean | Obsy AI サブスクリプション課金のスイッチ。 |
| content.tokenIpSet | object または null | ワークスペース Token の IP アクセス制限設定の動的オブジェクト。本ページでは返却のみで、これらのリクエストパラメータでは変更できません。 |
| content.singleConfig | object または null | ワークスペース機能設定の動的オブジェクト。ワークスペースに既存の設定を基準とし、ここで固定の設定キーを保証するものではありません。 |
| content.issueUpgrade | boolean | インシデントエスカレーション機能のスイッチ。 |
| content.durationSet.{データタイプ} | string | 当該データタイプの標準保持期間(rp、logging、keyevent、tracing、rum、apm、network、backup_log など)。現在の設定に応じて他の読み取り専用キーが存在する場合があります。 |
| content.storagePolicy.{データタイプ} | object | 当該タイプの長期ポリシー。通常は rp、logging です。 |
| content.storagePolicy.{データタイプ}.longStorageEnabled | boolean | 長期ストレージを有効にするか。 |
| content.storagePolicy.{データタイプ}.longStorageDuration | string | 長期の総保持期間(例: 180d)。無効化後は通常空文字列になります。 |
| content.datastore.{データタイプ} | string | 当該タイプが使用するエンジン名(例: es、doris、scopedb、volctls、sls、guancedb)。インスタンス UUID ではありません。 |
| content.declaration.organization | string | 組織名。宣言設定がある場合に提供されます。 |
| content.declaration.business | string | 業務の説明。宣言設定がある場合に提供されます。 |
| content.esIndexSettings.{データタイプ} | object | 対応するタイプのインデックス設定。 |
| content.esIndexSettings.{データタイプ}.number_of_shards | integer | プライマリシャード数。出現するかどうかはエンジンによって異なります。 |
| content.esIndexSettings.{データタイプ}.number_of_replicas | integer | レプリカ数。 |
| content.esIndexSettings.{データタイプ}.rollover_max_size | integer | シャードロールオーバーのしきい値。API はエンジンの定義に従って透過的に渡します。 |
| content.esIndexSettings.{データタイプ}.hot_retention | integer | ホットデータの保持期間(時間)。 |
| content.esIndexSettings.{データタイプ}.cold_retention | integer | オプションのコールドデータ保持期間(時間)。 |
| content.esIndexSettings.{データタイプ}.archive_retention | integer | オプションのアーカイブデータ保持期間(時間)。 |
| content.esIndexSettings.{データタイプ}.openAdvancedConfig | integer | 高度設定のフラグ。通常は 0 または 1 です。 |
| content.engineSetting.node_group | string | オプションのエンジンノードグループ識別子。その他の設定項目は対応するエンジンによって決まります。 |
| content.bindInfo.{設定項目} | JSON 値 | 既存のブランド上書き値。キーの意味はバインド情報設定 API に従います。 |
| content.lastDqlDataCheckTime.{データタイプ} | JSON 値 | 当該タイプのシステムが保守するチェック値であり、クエリ結果ではありません。 |
| content.tokenIpSet.{設定項目} | JSON 値 | 既存の Token IP ポリシー。読み取り後はその構造を保持し、これに基づいて External 認証ヘッダーを構築しないでください。 |
| content.singleConfig.{設定項目} | JSON 値 | 既存の機能設定値。具体的な型とキーは対応する機能の設定規約に従います。 |
| content.committed | boolean | 一部の同期 409 エラーでのみ返されます。true は削除済みマーク済み、false は今回保存されていないことを示します。 |
| content.syncStatus | string | 同期エラー時のみ提供され、通常は pending です。 |
| content.syncRequiresVerification | boolean | 一部の同期エラーで提供されます。true の場合は必ずダウンストリームの結果を検証する必要があります。 |
| content.syncFailureReason | string | 一部の同期エラーで提供されます(例: kodo_timeout、kodo_failed、verification_required)。 |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wksp_example001",
"status": 3,
"creator": "sys",
"updator": "sys",
"createAt": 1785427200,
"deleteAt": 1785427200,
"updateAt": 1785427200,
"name": "API サンプルワークスペース",
"token": "<workspace-token>",
"cliToken": "<workspace-cli-token>",
"dbUUID": "ifdb_example001",
"esInstanceUUID": "esinst_example001",
"dashboardUUID": "",
"exterId": "",
"rpName": "",
"desc": "API ドキュメントのデモ用ワークスペース",
"durationSet": {
"rp": "7d",
"logging": "7d",
"keyevent": "7d",
"tracing": "7d",
"rum": "7d",
"network": "1d"
},
"storagePolicy": {},
"datastore": {
"metric": "guancedb",
"logging": "doris",
"keyevent": "doris",
"tracing": "doris",
"rum": "doris",
"network": "doris",
"lineage": "doris"
},
"lastDqlDataCheckTime": {},
"declaration": {
"organization": "サンプル組織",
"business": ""
},
"esIndexSettings": {},
"bindInfo": {},
"versionType": "unlimited",
"billingState": "normal",
"bossStation": "",
"brandKey": "guance",
"enablePublicDataway": 1,
"isOpenLogMultipleIndex": 1,
"esIndexMerged": 0,
"supportJsonMessage": 1,
"isLocked": 1,
"lockMode": "writeLocked",
"lockAt": -1,
"delayDeleteAt": 1785427200,
"inviteAudit": 0,
"makeResourceExceptionCode": "",
"loggingCutSize": 10240,
"language": "zh",
"noviceGuide": false,
"timezone": "",
"menuStyle": "",
"tenantId": -1,
"isOpenCustomMappingRule": 0,
"enableRumMultipleTable": 1,
"enableMFA": false,
"disableQueryAcceleration": 0,
"disableDataWrite": 0,
"disableDataWriteAt": -1,
"logBackupQueryTimeLimit": 24,
"engineSetting": {},
"enableAI": false,
"enableAPIKeySecurityDisplayPolicy": false,
"enableObsyAISubscriptionBilling": false,
"tokenIpSet": {},
"singleConfig": {},
"issueUpgrade": true
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストのエラーについては共通エラー定義を参照してください。
下表は本 API の業務チェックおよび確認済みの主なエラー分岐を示します。ダウンストリームサービスは具体的なエラーに応じたマッピングにより他の 4xx エラーを返す場合があります。通常の 5xx および未知の例外はグローバル処理により ft.InternalServerError を返します。書き込みリクエストは、現在の設定とエラーの content を組み合わせて有効になったかどうかを判断する必要があり、HTTP ステータスのみでロールバックを推測することはできません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反している | パラメータの解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 406 | ft.NotFoundWorkspace | UUID が存在しない、または既に status=3 であり、初回クエリで見つからない | 指定されたワークスペースが見つかりません | ワークスペース一覧から有効な UUID を再取得し、ステータスを確認してください。 |
| 401 | ft.WKSPNotExistOrReleased | 初回クエリで 0 でも 3 でもない履歴状態のワークスペースが見つかったが、ライフサイクルロック内で status=0 が要求されている | ワークスペースが存在しない/または解放済みです | まず管理者にワークスペースのライフサイクル状態を確認してください。削除を繰り返し送信しないでください。 |
| 400 | ft.InvalidAction | サイトのシステムワークスペースを削除しようとした | 無効な操作 | システムワークスペースを保持し、まず管理者にワークスペースの用途を確認してください。 |
| 409 | ft.WorkspaceTokenSyncPending | ワークスペースに同期待ちの Token が既にある、またはワークスペースの削除マーク後に Token の同期に失敗した | 分岐に応じて「今回の操作は保存されていません」または「変更は保存されました」という同期のメッセージを返します | content.committed を確認して区別し、まずワークスペースの status と同期結果を確認してください。既に削除マーク済みの場合は削除を繰り返さないでください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、リソースサービス、または未処理のパラメータ変換の例外 | 内部エラー | traceId を保存して管理者に連絡してください。まず設定とダウンストリームの実際の状態を確認し、失敗レスポンスをそのまま未保存と見なしてはいけません。また、むやみに作成やローテーションを繰り返さないでください。 |