変更¶
POST /api/v1/workspace/modify
概要¶
現在のワークスペースの名前と説明を変更します。
呼び出し前の準備と使用手順¶
workspace.setManage 権限を持つ現在のワークスペースの API Key を使用します。name/desc のみをサポートし、バックエンドの完全なワークスペース設定を送り返すことはできません。省略した場合は対応する値が保持されます。{} を送信した場合も更新時刻が更新されキャッシュがリフレッシュされるため、厳密には無操作ではありません。
名前の変更はまずデータベースに保存され、その後ワークスペースのバージョン/請求センター設定に従って請求センターの名前を同期し、非同期でワークスペース認可内の名前を更新したうえで、キャッシュをリフレッシュします。後続で失敗した場合、新しい名前は既に保存済みで他のシステムはまだ古い名前のままである可能性があります。まずワークスペース名を読み戻し、管理者が請求センター/認可の同期を確認してから、失敗した部分を処理してください。成功しても、すべての非同期ノードが直ちに新しい名前を表示することを保証するものではありません。
レスポンスはワークスペースエンティティであり、現在のワークスペース詳細インターフェースの付加的な統計や change_data の返却は含みません。返却された uuid で対象を確認してください。デフォルト収集の token/cliToken などのフィールドは依然として機密クレデンシャルであるため、レスポンス全体を記録することは避けてください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証クレデンシャル。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作の権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| desc | string | オプションの文字列。省略時は保持、空文字列はクリアします。null は不可、格納列は 500 文字、500 文字以下を推奨します。 空文字列を許可: True null を許可: False 例: 更新後のワークスペース用途説明取得または入力方法: まず現在のワークスペースの content.desc から現在値を読み取ります。 |
|
| name | string | オプションの文字列。省略時は保持します。宣言上の最大長は 256 ですが格納列は 128 のため、128 文字以下を推奨します。現在は非空を強制していないため、空文字列を指定すると名前がクリアされる可能性があり、推奨しません。 null を許可: False 最大長: 256 例: API サンプルワークスペースの新名称取得または入力方法: まず現在のワークスペースの content.name から現在値を読み取ります。 |
パラメータ補足説明¶
変更対象は name と desc のみです。完全なワークスペース詳細をリクエストボディとして送信しないでください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"API サンプルワークスペースの新名称","desc":"更新後のワークスペース用途説明"}'
レスポンス¶
HTTP 200、application/json。以下の例では直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer | サイト内のレコード連番。以降の呼び出しでは uuid を使用します。 |
| content.uuid | string | ワークスペース UUID。 |
| content.status | integer | 0 は正常、3 は削除済みマーク。削除時の返却スナップショットは 3 です。 |
| content.creator | string | 作成者の識別子。新規作成時は通常、現在の呼び出し Key のリソース UUID です。 |
| content.updator | string | 最終更新者の識別子。未更新の場合は空になることがあります。 |
| content.createAt | integer | 作成時刻、Unix 秒。 |
| content.deleteAt | integer | 削除時刻、Unix 秒。未削除の場合は通常 -1。 |
| content.updateAt | integer | 更新時刻、Unix 秒。未更新の場合は通常 -1。 |
| content.name | string | ワークスペースの表示名。 |
| content.token | string | ワークスペースのデフォルト収集 Token。クレデンシャルとして保存され、OpenAPI の DF-API-KEY ではありません。例ではプレースホルダー値を使用しています。 |
| 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 を含むことがあります。これはワークスペースの列であり、外層の共通宣言ではありません。 |
| content.esIndexSettings | object または null | データ型ごとに保存されるインデックス設定オブジェクト。空オブジェクトはワークスペースレベルのカスタムテンプレートがないことを示し、下流にデフォルトテンプレートがないことを意味しません。 |
| content.bindInfo | object または null | ワークスペースのブランド文言、メール、ドメインのオーバーライドオブジェクト。キーの定義はバインド情報の設定を参照してください。 |
| content.versionType | string | ワークスペースのバージョン。例えば free、freeEdition、pay、enterprise、unlimited。作成時はサイト設定から取得され、このインターフェースはバージョンの入力パラメータを提供しません。 |
| 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 | シャードのロールオーバーしきい値。インターフェースはエンジンの定義に従ってそのまま渡します。 |
| 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 値 | 既存のブランドオーバーライド値。キーの意味はバインド情報設定インターフェースに準じます。 |
| content.lastDqlDataCheckTime.{データ型} | JSON 値 | その型のシステム保守チェック値。クエリ結果ではありません。 |
| content.tokenIpSet.{設定項目} | JSON 値 | 既存の Token IP ポリシー。読み取り後はその構造を保持し、これに基づいて OpenAPI 認証ヘッダーを構築しないでください。 |
| content.singleConfig.{設定項目} | JSON 値 | 既存の機能設定値。具体的な型とキーは対応する機能設定の取り決めによります。 |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "wksp_example",
"status": 0,
"creator": "wsak_source",
"updator": "wsak_source",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": 1785427300,
"name": "API サンプルワークスペースの新名称",
"token": "<workspace-token>",
"cliToken": "<workspace-cli-token>",
"dbUUID": "ifdb_example001",
"esInstanceUUID": "esinst_example001",
"dashboardUUID": "",
"exterId": "",
"rpName": "",
"desc": "インターフェースドキュメントのデモ用ワークスペース",
"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": {},
"esIndexSettings": {},
"bindInfo": {},
"versionType": "unlimited",
"billingState": "normal",
"bossStation": "",
"brandKey": "guance",
"enablePublicDataway": 1,
"isOpenLogMultipleIndex": 1,
"esIndexMerged": 0,
"supportJsonMessage": 1,
"isLocked": 0,
"lockMode": "none",
"lockAt": -1,
"delayDeleteAt": -1,
"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"
}
エラー応答¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
請求センターの呼び出しが必要な場合、明確な上流の 4xx は実際の HTTP と ft.CloudCareApiError を保持し、message は上流の業務メッセージに従います。通常の 5xx/タイムアウトは最終的に 500 ft.InternalServerError に統一されます。まずワークスペースの保存済み状態と請求センターの結果を確認し、失敗だけを根拠に直ちに再作成しないでください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータの解析に失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトでない | 一部の json ファイルの形式エラー | 本ページのパラメータに従って JSON オブジェクトを送信してください。 |
| 406 | ft.NotFoundWorkspace | 現在のワークスペースが存在しない/アクティブ条件を満たさない | 指定されたワークスペースが見つかりません | 現在の Key に対応するワークスペースの状態を確認してください。 |
| 406 | ft.InvalidBossNode | 請求センターの同期が必要だが、サイトのブランド/ノードが未設定 | 無効な Boss ノード | 管理者に請求センターノードの確認を依頼してください。ワークスペース名は既に保存されている可能性があります。 |
| 500 | ft.InternalServerError | データベース、キャッシュ/キュー、下流の通常 5xx/タイムアウト、または未処理の型の失敗。書き込みが既にコミットされている可能性があります | 内部エラー | まず現在/対象のワークスペース詳細と下流の状態から保存済みの結果を確認し、むやみに再作成/ローテーションを繰り返さないでください。既に保存済みの場合は未完了の同期のみを処理し、traceId を提供してください。 |