コンテンツにスキップ

変更



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 を提供してください。

フィードバック

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