インデックスのキーフィールド変更¶
POST /api/v1/workspace/index_key_field/modify
概要¶
選択したログインデックスのキーフィールドを一括更新し、グローバルスイッチに従ってフィールドの高速化を同期します。
呼び出し前と使用手順¶
ワークスペースは API Key によって特定されます。ログインデックス/エクスプローラーの管理権限を持つ Key を使用してください。キーフィールド設定はログ表示とオプションの高速化を制御しますが、実際のログフィールド名、過去のログ値、単位説明は変更しません。インデックス UUID とインデックス名は混在して使用できません。
まず設定を読み取ってバックアップし、syncKeywordSpeed を明確にしたうえで、各インデックスの完全な extendFields を送信してください。uuid が重複する場合は最後の項目が有効になり、default は優先して処理され、その他の UUID はまず現在のワークスペースで有効なレコードを検索します。デフォルト以外のインデックスの同時実行関係ロックで例外が発生すると 429 になる場合があります。再試行前に設定を再読み取りしてください。選択したインデックスのキーフィールドのみを上書きし、そのインデックスのその他の設定は保持します。この API をフィールドタイプ/全文インデックス/インデックスの保持期間の変更として使用しないでください。
syncKeywordSpeed はデフォルトで true です。オフからオンに変更すると、すべてのインデックスのキーフィールドを同期します。すでに有効な場合は、今回のバッチで新たに出現したフィールドのみ高速化を作成します。false を指定すると、今回の処理だけをスキップするのではなく、グローバルな自動同期が無効として保存されます。既存の高速化フィールドは能動的に削除せず、extendFields を空にしても高速化は能動的に削除されません。デフォルト値により、cfgList を省略した場合でもグローバル同期がトリガーされる可能性があるため、呼び出し側は明示的に決定する必要があります。
設定を先に送信し、その後で高速化をディスパッチします。重複排除後の (index,field) 操作が 200 件未満の場合は同期的に処理されます。より大きなバッチは 200 件ずつに分割してバックグラウンドで投入され、投入に失敗した場合は同期処理にフォールバックできます。個別の下流高速化の失敗は記録されますが、必ずしもこの API の失敗にはなりません。HTTP 200/true は設定処理とディスパッチ経路の完了のみを示し、高速化がすべて完了したことを保証しません。このレスポンスにはタスク ID やフィールドごとの成功リストはありません。書き込み後にキーフィールドを読み戻し、実際の高速化は別途確認してください。失敗時に設定がロールバックされたと仮定しないでください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| cfgList | array | 任意の配列。省略または [] を指定しても特定のインデックスフィールドは変更しませんが、グローバルの syncKeywordSpeed はデフォルトの true として処理されます。空のバッチを厳密な無操作として扱わないでください。 null を許可: False 例: [{"uuid": "default", "extendFields": [{"tag": "host", "alias": "主机"}, {"tag": "service", "alias": "服务"}]}]取得または入力方法: まずキーフィールドの読み取りから cfg_uuid を読み取り、引き続き必要なフィールドを完全に戻します。 |
|
| cfgList[*] | object | 各項目は本ページの構造に従って送信する必要があります。uuid/extendFields が欠落している場合、または子項目が公開宣言に適合しない場合は、まず 406 になります。uuid が重複する場合、後の項目が前の項目を上書きします。 例: {"uuid": "default", "extendFields": [{"tag": "host", "alias": "主机"}, {"tag": "service", "alias": "服务"}]}取得または入力方法: 各オブジェクトは 1 つのインデックス設定に対応します。 |
|
| cfgList[*].extendFields | array | 条件付き必須 | そのインデックスの完全なキーフィールドリスト。元の値を上書きします。[] はクリアに使用します。空文字列は過去の宣言との互換性がありますが、ビジネス層では引き続き 400 になるため、クリアには使用しません。リストの順序は保持され、フィールドを削除しても、そのフィールドに既存の高速化インデックスが自動的に削除されることはありません。 空文字列を許可: True null を許可: False 例: [{"tag": "host", "alias": "主机"}, {"tag": "service", "alias": "服务"}]取得または入力方法: 読み取り結果から完全なリストをコピーし、その後でフィールドを追加または削除します。 |
| cfgList[*].extendFields[*] | object | tag と alias のみを許可し、tag は空でない必要があります。公開宣言では通常、オブジェクト以外、余分なサブキー、フィールドタイプの誤りがまず 406 として拒否されます。 例: {"tag": "host", "alias": "主机"}取得または入力方法: 項目ごとに実際のフィールド名と任意の表示別名を入力します。 |
|
| cfgList[*].extendFields[*].alias | string | 任意の別名。実際のフィールドとの照合には使用されません。 空文字列を許可: True null を許可: False 例: 主机取得または入力方法: 表示要件に応じて入力します。不要な場合は省略するか空文字列にします。 |
|
| cfgList[*].extendFields[*].tag | string | 条件付き必須 | 必須の実際のフィールド名。クライアントは空でない文字列を使用し、別名は入力しません。 null を許可: False 例: host取得または入力方法: 実際のログフィールド名を使用します。SHOW_LOGGING_FIELD(index=...) で照会できます。 |
| cfgList[*].uuid | string | 条件付き必須 | インデックス設定 UUID。通常のインデックス名では代用できません。default 以外の場合は、まず現在のワークスペースで有効なレコードを検索し、関係ロックを取得します。未知/削除済み/別ワークスペースの UUID は 404 になる可能性があります。一律に無視されるわけではありません。 null を許可: False 例: default取得または入力方法: キーフィールドの読み取りの cfg_uuid を取得します。またはログインデックス一覧から uuid を取得します。デフォルト項目は固定で default です。 |
| syncKeywordSpeed | boolean | 任意のブール値。省略時はデフォルトで true になり、グローバル同期が再び有効になる可能性があります。false は今回の処理だけをスキップするのではなく、グローバルな自動同期を無効にします。既存の高速化インデックスは削除しません。 null を許可: False 例: false取得または入力方法: ワークスペース管理者がグローバルなキーワード自動高速化ポリシーを決定します。この読み取り API はこのスイッチを返しません。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/workspace/index_key_field/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"cfgList":[{"uuid":"default","extendFields":[{"tag":"host","alias":"主机"},{"tag":"service","alias":"服务"}]}],"syncKeywordSpeed":false}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | boolean | 正常時に true を返します。インデックスごと/高速化フィールドごとの完了状態ではありません。 |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
キーフィールド同期における通常の Kodo 高速化の失敗は、通常は呼び出し元に伝播されず記録されるため、すべての下流の件数/インデックスエラーをこの API が必ず透過的に返すエラーとして列挙しているわけではありません。ロック所有権などの事前/シャードチェックによっては、引き続きリクエストが失敗する可能性があります。
| HTTP ステータス | errorCode | トリガー条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落しているか、フィールド値が宣言された検証条件に違反しています | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | リクエスト JSON のトップレベルがオブジェクトではありません | 一部の JSON ファイル形式エラー | 設定 JSON オブジェクトを送信してください。 |
| 400 | ft.InvalidLogIndexCfgKeyFields | 公開検証を通過した後もキーフィールド構造に適合しない場合。たとえば extendFields の空文字列が過去互換性検証を通過した後にビジネス配列検証へ進む場合です | 不正なログインデックスのキーフィールド | 構造に従って入力し、実際のフィールド名を保持してください。 |
| 404 | ft.LogIndexCfgNoExists | ロック前に default 以外のインデックスを特定する際、現在のワークスペースで有効な設定が見つかりませんでした | 指定されたログインデックス設定が存在しません | インデックス UUID を再読み取りし、削除済みまたは別ワークスペースのレコードを除外してください。 |
| 429 | ft.OperationTooFrequently | インデックス関係ロックが利用できない、取得に失敗した、または実行中にロックのリース期間が失われた | 操作が頻繁すぎます。しばらくしてから再試行してください | しばらくしてから再試行する前に、送信済み設定を読み戻し、同時実行による重複バッチを避けてください。 |
| 500 | ft.InternalServerError | 設定の読み取り、保存、キャッシュ、または下流処理で未制御の例外が発生しました | 内部エラー | traceId を保持し、書き込みリクエストでは先に完了済み項目を読み取り/確認してから再試行を判断してください。 |