ワークスペース - インデックステンプレート設定¶
POST /api/v1/workspace/{workspace_uuid}/update_index_setting
概要¶
指定したワークスペースのデータ型におけるインデックステンプレート、ホットストレージ、マッピング、保持ポリシーを更新します。
呼び出し前の確認と使用手順¶
まずインデックステンプレート一覧を呼び出し、現在のデータ型、ストレージエンジン、マージモード、および対象ログインデックスの UUID を確認し、現在値をバックアップしてから変更してください。テンプレートパラメータはエンジンの機能制限を受けます。ES はシャード/レプリカ/高度なマッピングをサポートし、Doris は主にホットストレージを設定し、VolcTLS はホット/コールド/アーカイブを設定します。SLS/Beaver では本インターフェースは禁止されています。テンプレートまたは mappings の変更を適用するには、hotRetention を同時に送信する必要があります。この場合、テンプレートはサイトのデフォルトから構築された後、今回のパラメータで上書きされ、既存テンプレートとのフィールドマージは行われません。シャード、レプリカ、ロールオーバーしきい値、高度な設定スイッチなどを省略すると、デフォルトに戻るか古い値が削除され、既存の高度な設定が無効になる可能性があります。事前に完全な対象テンプレートを読み取り、送信する必要があります。以下のリクエスト例は、datastore.logging=doris が確認済みのワークスペースにのみ適用されます。ES では完全なテンプレートを使用し、VolcTLS では各層の目標期間を同時に明示してください。保持期間のみを変更する場合は、duration または storagePolicy を送信できます。mappings の省略は古いマッピングの自動マージではありません。高度な設定を有効にする場合は、事前に完全なマッピングを取得してください。成功後はインデックステンプレートを再読み取りして確認してください。下流の更新とデータベースのコミットは同一トランザクションではないため、失敗時はまず両端の実際の状態を確認してください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 秒を生成します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| storagePolicy.longStorageEnabled | boolean | false は明示的な無効化です。storagePolicy オブジェクトを送信する場合、このキーを省略すると false に正規化され、元のポリシーが無効になる可能性があります。元のポリシーを維持するには、storagePolicy オブジェクト全体を省略してください。 例: false取得または入力方法: JSON のブール値で有効または無効を選択し、エンジンとバージョンの条件を満たす必要があります。 |
|
| storagePolicy.longStorageDuration | string | 有効時は指定します。無効時は省略できます。 例: 180d取得または入力方法: サイトで許可された集合から選択し、現在または今回の duration より大きい必要があります。 |
|
| mappings.{映射项} | any | 自由構造です。1 つの例のマッピングキーを、すべてのエンジンがサポートする共通フィールドとして扱うことはできません。 例: {}取得または入力方法: サイト管理者がインデックスエンジンの既存マッピング設定からエクスポートし、そのエンジンの構造を維持します。 |
|
| archiveRetention | int | 任意の整数、単位は時間です。VolcTLS のデフォルト範囲は 60~1800 日で、ホットストレージは少なくとも 30 日です。ホット、コールド、アーカイブの合計期間は 1800 日を超えてはならず、実際のサイト範囲で上書きされる場合があります。 null の許可: False 例: 1440取得または入力方法: VolcTLS のみ、アーカイブストレージの要件に応じて提供し、完全な日数分を時間単位で入力します。 |
|
| cfg_uuid | string | 任意。logging のみがこの UUID による独立したログインデックスの選択をサポートします。ログ以外の型では指定しないでください。インデックスは対象ワークスペースに属し、削除されていない必要があります。 空文字列の許可: True null の許可: False 例: 取得または入力方法: デフォルトインデックスの場合は省略または空文字列にします。カスタムログインデックスを変更する場合は、インデックステンプレート一覧 の content.otherLogIndexSettings[].uuid から取得します。 |
|
| coldRetention | int | 任意の整数、単位は時間です。現在は VolcTLS で検証後に適用されます。他のエンジンが受け入れるかどうかは下流で決定され、汎用機能と見なすべきではありません。VolcTLS のデフォルト範囲は 30~1800 日で、ホットストレージを同時に指定する必要があり、少なくとも 7 日必要です。 null の許可: False 例: 720取得または入力方法: VolcTLS のみ、低頻度ストレージの要件に応じて提供し、完全な日数分を時間単位で入力します。 |
|
| data_type | string | Y | 必須の列挙値 rum、logging、network、tracing、profiling、keyevent、security、backup_log、apm、dialtest。マージモードでは通常 apm を使用し、分割モードでは tracing/rum/profiling などを使用します。本 External 宣言は rp または lineage をサポートしないため、他の実行環境の入力をそのままコピーできません。 null の許可: False 選択可能な値: ['rum', 'logging', 'network', 'tracing', 'profiling', 'keyevent', 'security', 'backup_log', 'apm', 'dialtest'] 例: logging取得または入力方法: インデックステンプレート一覧 から datastore と esIndexMerged を確認したうえで、そのモードに実際に存在するデータ型を選択します。 |
| duration | string | 任意の標準合計保持期間で、数値に d を付けます。省略または空文字列の場合は元の値を使用します。VolcTLS 以外のワークスペースレベルおよびカスタムログインデックスは保持期間変更の対象になります。VolcTLS のワークスペースレベルでは主に hot/cold/archive から標準合計期間を計算します。バージョンごとの許可集合/範囲の制限を受けます。 null の許可: False 例: 7d取得または入力方法: インデックステンプレート一覧 の durationSet で該当する型またはカスタムインデックスの duration を読み取ってから調整します。 |
|
| hotRetention | int | 任意の整数、単位は時間です。0 を使用できるかどうかはエンジンによって決まり、負の数は拒否されます。ES/Doris ではホットデータ期間を設定できます。VolcTLS では正の整数で、1 日単位の時間数を指定する必要があります。テンプレートまたは mappings を変更する場合は本フィールドを同時に指定する必要があり、シャード/高度なフィールドのみを送信しても現在は適用されません。hotRetention が存在する場合、サイトのデフォルトで今回のテンプレートが補完され、他の古いフィールドを省略するとそれらがリセットされる可能性があります。部分マージ更新ではありません。 null の許可: False 例: 24取得または入力方法: インデックステンプレート一覧 の現在の esIndexSettings または otherLogIndexSettings[].setting.hot_retention から読み取ります。 |
|
| mappings | json | 任意の JSON オブジェクトで、インデックス UUID ではありません。マッピング構造は下流エンジンによって定義され、Studio はオブジェクトをそのまま透過的に渡し、各動的マッピング項目に共通型を定義しません。hotRetention が存在し、openAdvancedConfig が真の場合にのみ更新を試みます。省略時は {} がデフォルトになり、有効にする場合は空オブジェクトによる上書きを避けるため、確認済みの完全なマッピングを送信する必要があります。 null の許可: False 例: {}取得または入力方法: サイト管理者が現在のインデックスの高度なマッピング設定から完全なオブジェクトを取得します。この External モジュールは mappings を読み取るインターフェースを公開していません。 |
|
| number_of_replicas | int | 任意のレプリカ数、整数、ES で使用します。0 がレプリカ未設定を意味するかどうかはエンジンによって決まります。Doris/VolcTLS はこのフィールドの出現をサポートせず、テンプレート変更には hotRetention が必要です。hotRetention が存在する場合、サイトのデフォルトで今回のテンプレートが補完され、他の古いフィールドを省略するとそれらがリセットされる可能性があります。部分マージ更新ではありません。 null の許可: False 例: 1取得または入力方法: ES の高可用性要件に応じて選択し、事前にサイトのレプリカポリシーを確認します。 |
|
| number_of_shards | int | 任意のプライマリシャード数、整数、ES で使用します。Doris/VolcTLS はこのフィールドの出現をサポートしません。hotRetention を同時に指定する必要があり、そうでない場合このテンプレート変更は適用されません。hotRetention が存在する場合、サイトのデフォルトで今回のテンプレートが補完され、他の古いフィールドを省略するとそれらがリセットされる可能性があります。部分マージ更新ではありません。 null の許可: False 例: 1取得または入力方法: まずインデックステンプレート一覧 で現在値と ES のサポート能力を確認し、管理者の推奨に従って選択します。 |
|
| openAdvancedConfig | int | 任意の整数で、0/1 を推奨します。ES では設定できます。Doris/VolcTLS は 0 を送信してもこのフィールドの出現をサポートせず、SLS/Beaver では本インターフェースのインデックス設定が禁止されています。hotRetention と一緒に送信した場合にのみ高度な設定を処理します。hotRetention が存在する場合、サイトのデフォルトで今回のテンプレートが補完され、他の古いフィールドを省略するとそれらがリセットされる可能性があります。部分マージ更新ではありません。 null の許可: False 例: 0取得または入力方法: 現在のインデックス設定から読み取り、0 で無効、1 で有効を選択します。高度な設定をサポートするエンジンでのみ使用します。 |
|
| rollover_max_size | int | 任意の整数で、基盤インデックスのロールオーバー/分割しきい値です。Studio は単位変換を行わず、ログのバイト分割サイズ loggingCutSize として扱うべきではありません。この設定をサポートする ES パスでのみ使用し、hotRetention を指定する必要があります。hotRetention が存在する場合、サイトのデフォルトで今回のテンプレートが補完され、他の古いフィールドを省略するとそれらがリセットされる可能性があります。部分マージ更新ではありません。 null の許可: False 例: 30取得または入力方法: 対象ストレージエンジンのシャードロールオーバーポリシーに従って指定し、事前にサイト管理者へそのエンジンのしきい値単位を確認します。 |
|
| storagePolicy | json | 任意の単一タイプの長期ストレージポリシーオブジェクトで、logging キーでラップしません。省略すると元のポリシーを維持します。単一ポリシーで {} を送信すると longStorageEnabled=false に正規化され、既存の長期ストレージが無効になる可能性があるため、無効化を表す場合は明示的に false を送信することを推奨します。現在公開されているタイプでは、logging にのみ長期ストレージを設定することを推奨します。ログで有効化できるのは scopedb のみです。長期ストレージは合計保持期間であり、そのタイプの標準保持期間より大きい必要があります。ログは scopedb かつ pay/enterprise/unlimited のみサポートされます。メトリクスは課金タイプに適合する必要があり、pay と請求センターが有効な unlimited では metric_point_total が必要で、enterprise なども明示的な timeseries 課金を拒否します。リポジトリのデフォルトでは、pay のログは 90d/120d/180d/360d を選択できます。pay のメトリクスはさらに 540d/720d を選択できます。enterprise/unlimited のログは 1d~1800d、メトリクスは 1d~3600d が許可され、なおかつ標準保持期間より大きい必要があります。実際の選択可能な集合と範囲はサイト設定によって上書きされます。 null の許可: False 例: {"longStorageEnabled": false}取得または入力方法: インデックステンプレート一覧 の対応するワークスペースレベルまたはカスタムログインデックスの storagePolicy から取得します。 |
パラメータ補足説明¶
w 権限を持つサイトレベルの External API 資格情報を使用します。認証方式はExternal API 署名認証を参照してください。例は v20240417 に従って署名を計算し、署名と送信で同じパス、Query、元のリクエストボディを使用します。すべての例はデモ用の値であり、実行前に実際の対象へ置き換えてください。書き込みリクエストがタイムアウトまたは 500 になった場合は、まず現状を問い合わせ、確認してから再試行するかどうかを決定してください。
VolcTLS のホット、コールド、アーカイブパラメータは統一して時間単位で送信し、標準 duration は日単位で表示します。各層のデフォルト範囲はサイトで上書きされる場合があります。完全なルールはパラメータ表を参照してください。
ES の完全な対象リクエストボディ例: まずインデックステンプレート一覧から現在値をコピーし、調整が必要な値だけを変更します。以下の数値は例にすぎません。openAdvancedConfig=1 の場合は、管理者が提供する完全な mappings オブジェクトを同時に送信する必要があり、このスイッチを省略すると元の高度な設定が無効になる可能性があります。
{
"data_type": "logging",
"hotRetention": 24,
"number_of_shards": 1,
"number_of_replicas": 1,
"rollover_max_size": 30,
"openAdvancedConfig": 0
}
リクエスト例¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# この例は、datastore.logging=doris が確認済みのワークスペースにのみ使用します。
# ES では先に完全な対象テンプレートを読み取って送信する必要があり、ホットストレージのみのパラメータをそのままコピーできません。
# 対象サイトのアドレスおよび管理者が割り当てた 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/update_index_setting'
query = {}
data = {'data_type': 'logging', 'hotRetention': 24}
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 | boolean | 成功時は true です。更新フィールドの一覧ではありません。hotRetention が欠けている場合、一部のテンプレートフィールドは無視される可能性があり、true だけからすべての項目が適用されたと判断することはできません。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。
下表は、本インターフェースの業務検証および確認済みの主なエラーブランチを示します。下流サービスは具体的なエラーマッピングに応じて他の 4xx エラーを返す場合があります。通常の 5xx および未知の例外はグローバル処理を経て ft.InternalServerError を返します。書き込みリクエストは、現在の設定とエラーの content を組み合わせて有効化されたかどうかを判断する必要があり、HTTP ステータスだけでロールバックを推測することはできません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンス説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではありません | 一部の JSON ファイル形式エラー | パラメータ表に従って JSON オブジェクトを送信し、配列や null をリクエストボディ全体として扱わないでください。 |
| 406 | ft.NotFoundWorkspace | ワークスペースが存在しない、削除済み、または現在のアクティブ状態の問い合わせ条件を満たさない | 指定されたワークスペースが見つかりません | ワークスペース一覧から有効な UUID を再取得し、状態を確認してください。 |
| 429 | ft.OperationTooFrequently | 同一ワークスペースのストレージ設定ロックが使用中、または実行中にロックの所有権を失った | 操作が頻繁すぎます。しばらくしてから再試行してください | しばらくしてから現在の設定を先に読み取り、新しい nonce と署名で再試行してください。実行中にロックを失った場合、すべての書き込みが発生していないと断定することはできません。 |
| 400 | ft.InvalidAction | data_type は宣言された列挙値内にあるが、現在のマージ/分割モードのサポート集合に含まれない | 無効な操作 | まずインデックステンプレートを確認し、そのワークスペースで実際にサポートされている型を使用してください。 |
| 404 | ft.NamespaceDatastoreNotFound | 現在のデータ型に有効なストレージエンジン設定がない | {} のストレージタイプが見つかりません | まずインデックステンプレートで datastore にその型が存在することを確認し、設定が欠けている場合は管理者に依頼してください。 |
| 404 | ft.ForbiddenIndexCfg | 対象の型が SLS または Beaver を使用しており、本インターフェースのインデックス設定をサポートしない | sls/beaver ストレージタイプのインデックス設定はサポートされていません | 対応するストレージサービスの正式な設定機能を使用するか、サイト管理者に調整を依頼してください。 |
| 404 | ft.ForbiddenAdvancedCfg | Doris または VolcTLS のリクエストに openAdvancedConfig が含まれている | ストレージタイプ {} の高度な設定はサポートされていません | このフィールドと mappings を削除し、エンジンのサポート能力に応じて設定してください。 |
| 404 | ft.ForbiddenShardReplicasCfg | Doris または VolcTLS のリクエストにシャード/レプリカ/ロールオーバーしきい値フィールドが含まれている | ストレージタイプ {} のシャード/レプリカ設定はサポートされていません | number_of_shards、number_of_replicas、rollover_max_size を削除してください。 |
| 406 | ft.InvalidParameter | hotRetention が負の数 | パラメータ {} が無効です |
エンジンがサポートする非負の値を時間単位で指定してください。VolcTLS では正の 1 日単位の時間数である必要があります。 |
| 404 | ft.LogIndexCfgNoExists | 保持期間またはホットストレージ更新に使用する cfg_uuid が現在のワークスペースに属していない、または削除済み | 指定されたログインデックス設定が存在しません | 現在のワークスペースのインデックステンプレート一覧からカスタムログインデックスの UUID を再取得してください。 |
| 404 | ft.MissingVolctlsHotRetention | VolcTLS リクエストで有効な hotRetention が提供されていない | Volcengine ストレージ、標準ストレージ(ホットストレージ)フィールドが欠落しています | 正の整数のホットストレージ時間数を指定してください。 |
| 400 | ft.InvalidHotRetention | VolcTLS のホットストレージが 24 の整数倍ではない | Volcengine ストレージ、無効なホットデータ保存期間です。1 日単位の時間数である必要があります | ホットストレージの日数に 24 を掛け、完全な日数分の時間を指定してください。 |
| 400 | ft.InvalidRetentionFullDayhours | VolcTLS のコールドストレージまたはアーカイブが 24 の整数倍ではない | Volcengine ストレージ、無効な {} 保存期間です。1 日単位の時間数である必要があります | 対応する日数に 24 を掛けて送信してください。 |
| 400 | ft.InvalidRetention | VolcTLS のいずれかの層の期間がサイトの許可範囲を超えている | Volcengine ストレージ、無効な {} 保存期間です。範囲は {} 日です | ホット/コールド/アーカイブそれぞれの範囲に合わせて調整してください。 |
| 400 | ft.InvalidColdRententionHot | VolcTLS のコールドストレージを設定しているが、ホットストレージがサイトの最小要件未満 | ストレージエンジンに低頻度ストレージが存在する場合、標準ストレージは {} 日以上である必要があります | デフォルトではホットストレージは少なくとも 7 日必要です。実際のサイト要件に合わせて調整してください。 |
| 400 | ft.InvalidArchiveRententionHot | VolcTLS のアーカイブを設定しているが、ホットストレージがサイトの最小要件未満 | ストレージエンジンにアーカイブストレージが存在する場合、標準ストレージは {} 日以上である必要があります | デフォルトではホットストレージは少なくとも 30 日必要です。実際のサイト要件に合わせて調整してください。 |
| 400 | ft.InvalidAllRetention | VolcTLS の各層の合計期間がサイト範囲を超えている | Volcengine ストレージ、無効な合計保存期間です。範囲は {} 日です | デフォルトでは合計期間は 1800 日を超えません。各層の組み合わせを調整してください。 |
| 400 | ft.FreeWKSPLimit | 無料プランで標準保持期間または長期ストレージポリシーの変更を試行 | 無効な操作です。現在のワークスペースは無料プランです | 元の値を維持するか、正式なアップグレード手順で処理してください。 |
| 406 | ft.InvalidDuration | 標準または長期保持期間の形式または選択可能な値が無効 | 無効な duration | そのバージョンで選択可能な値を使用し、形式は数値に d を付けます。 |
| 406 | ft.InvalidDurationRange | 標準保持期間が範囲外、または長期保持期間が標準値以下 | 有効なデータ保持期間の範囲を超えています | 実際のバージョン範囲に合わせて調整してください。 |
| 400 | ft.InvalidActionForbiddenChange | ログ長期ストレージのエンジンまたはバージョンがサポートしていない | 具体的な分岐に応じて長期ストレージがサポートされない理由を返します | 許可されたバージョンの scopedb ログワークスペースでのみ有効化してください。 |
| 406 | ft.CurrentVersionUnsupportRp | バージョンが保持期間の編集をサポートしていない | 現在のバージョンは rp:{} をサポートしていません |
管理者にワークスペースのバージョンを確認してください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ、リソースサービス、または未処理のパラメータ変換例外、あるいはインデックステンプレート更新の下流レスポンスに成功マークが含まれていない | 内部エラー | traceId を保存して管理者に連絡してください。まず設定と下流の実際の状態を問い合わせ、失敗レスポンスをそのまま保存されていないと見なさず、やみくもに作成やローテーションを繰り返さないでください。 |