インデックス高速化フィールド設定の変更¶
POST /api/v1/workspace/index_speed_field/modify
概要¶
フィールド高速化を順番に追加または削除し、最初の失敗で停止し、完了済みの項目は保持します。
呼び出し前の確認と使用手順¶
対象ワークスペースのログインデックス管理権限を持つ Key を使用します。フィールド高速化をサポートするストレージエンジン/データカテゴリで呼び出します。典型的なのは ScopeDB ログです。まずログインデックス一覧からインデックスの name を特定し、次に実際のフィールド名と必要な高速化タイプを取得します。この API はキーフィールドの表示設定とは異なり、extendFields を変更しません。
namespace=logging、完全な fieldSpeedConfig、enable を明示的に送信します。namespace に有効なマッピングがない場合、成功レスポンスのエンベロープ内では content=false となり、呼び出し元はブール値を確認する必要があり、HTTP 200 だけで実行済みと判断してはいけません。namespace が有効で配列が空の場合、true であってもフィールドの変更を意味しません。すべての indexType を先にチェックし、その後フィールドごとに順番に実行します。最初の失敗で直ちに停止し、成功済みのフィールドは保持し、後続は実行しません。一括ロールバックやプログラム内での自動リトライは行いません。
削除時は特に注意してください。indexType=search は転置インデックスのみを削除します。省略/null/空文字列/materialized はすべて空の型にマッピングされ、すべての高速化インデックスタイプを削除します。範囲を確認してから削除を送信してください。失敗時は実際のエラーに応じて修正した後、既存の冪等操作を再試行できますが、まず成功済みの項目と数量上限を確認する必要があります。項目ごとのステータス/タスク ID がないため、バッチ全体が未実行であると断言することはできません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報です。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| fieldSpeedConfig | array | オプションの配列です。省略または [] の場合、namespace が有効であれば true を返し、フィールド操作は行いません。すべての indexType を事前チェックしてから、元の順序で項目ごとに実行します。重複排除は行いません。 null を許可: False 例: [{"index": "default", "field": "host", "enable": true, "indexType": "search"}]取得または入力方法: インデックス一覧から name を取得し、ログフィールドクエリから実際の field を取得します。 |
|
| fieldSpeedConfig[*] | object | クライアントは完全なオブジェクト構造を送信する必要があります。null やオブジェクト以外を送信しないでください。 例: {"index": "default", "field": "host", "enable": true, "indexType": "search"}取得または入力方法: 各項目に 1 つの高速化フィールド操作を指定します。 |
|
| fieldSpeedConfig[*].enable | boolean | 条件付き必須 | 各項目でブール値を明示的に送信する必要があります。欠落している場合や型が一致しない場合は、公開パラメータ層で先に 406 となり、controller 内部のデフォルト false には依存しません。 null を許可: False 例: true取得または入力方法: 高速化を作成する場合は true、削除する場合は false を指定します。 |
| fieldSpeedConfig[*].field | string | 条件付き必須 | 高速化する実際のフィールド名であり、エイリアスではありません。 null を許可: False 例: host取得または入力方法: SHOW_LOGGING_FIELD(index=...) などのクエリで実際のフィールド名を取得します。 |
| fieldSpeedConfig[*].index | string | インデックス名であり、UUID ではありません。Studio ではここでインデックス設定を先に確認せず、最終的な有効性は下流で判断されます。 null を許可: False 例: default取得または入力方法: ログインデックス一覧の name を取得し、省略時は default を使用します。 |
|
| fieldSpeedConfig[*].indexType | string | 空文字列/materialized/search のみをサポートし、null は空として扱われます。空/materialized を新規追加する場合は通常タイプを指定します。空/materialized を削除する場合は、すべての高速化インデックスタイプが削除されます。転置インデックスのみを削除する場合は search を明示的に指定してください。 空文字列を許可: True null を許可: True 例: search取得または入力方法: 転置インデックスの高速化のみが必要な場合は search を指定し、通常/マテリアライズドの場合は materialized を指定するか省略します。 |
|
| namespace | string | オプションですが、欠落している場合や未知のマッピングの場合は HTTP 200 かつ content=false となり、操作は実行されません。Studio ではここでサイトマッピングに従って変換し、logging 以外であるという理由だけで一律に拒否することはありません。具体的なデータカテゴリ/エンジンのサポートは下流でチェックされ、現在の典型は ScopeDB ログです。 null を許可: False 例: logging取得または入力方法: ログフィールドの高速化では logging を指定することを推奨します。全称を小文字で指定し、L は指定しません。 |
|
| source | string | オプションです。元の値がそのまま下流に転送され、省略時は source フィルタを送信しません。インデックス名ではありません。 null を許可: False 例: nginx取得または入力方法: ソースを限定する必要がある場合は実際の source を指定し、不要な場合は省略します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/index_speed_field/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"namespace":"logging","fieldSpeedConfig":[{"index":"default","field":"host","enable":true,"indexType":"search"}]}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | namespace が未マッピングの場合は false、有効なマッピングでループが完了した場合は true、空のバッチでも true です。フィールドごとのレポートではありません。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
その他、下流のインデックスが存在しない場合、エンジン機能、権限エラーは、実際の HTTP/errorCode/message に従ってそのまま返される場合があります。未制御の 5xx は共通エラーによって 500 にラップされ、固定の動的コードを偽装しません。数量が上限に達した場合は通常 406 となり、この API はその作成エラーを握りつぶしません。これはキーフィールド設定のバックグラウンド同期とは異なります。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンス説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトではありません | 一部の json ファイルの形式エラー | 例に従ってオブジェクトを送信してください。 |
| 406 | ft.InvalidParameter | namespace マッピングが有効で、いずれかの indexType が空/materialized/search ではない | パラメータ {} が無効です |
対象操作に応じて有効なタイプを選択してください。バッチ全体の indexType 事前チェックで先に拒否されます。 |
| 406 | ft.KodoFieldIndexLimitReached | 下流で高速化インデックスを作成する際に数量上限に達しました | 現在のインデックスの高速化フィールド数が上限に達しました。最大 {} 個まで許可されています。不要な高速化フィールドを削除してから再試行してください。 | message に示された上限に従って不要な高速化フィールドを削除し、未完了の項目を再試行してください。 |
| 500 | ft.InternalServerError | 設定の読み取り、ストレージ、キャッシュ、または下流処理で未制御の例外が発生しました | 内部エラー | traceId を保持し、書き込みリクエストの場合は先に完了済み項目を読み取り/確認してから、再試行を判断してください。 |