追加¶
POST /api/v1/field_cfg/add
概要¶
現在のワークスペースにカスタムフィールドの説明、別名、表示単位の設定を作成します。
呼び出し前の準備と使用手順¶
対象ワークスペースの API Key を使用します。この設定は既存フィールドに表示別名、説明、単位、分類を追加するもので、収集フィールドの作成、実際のデータ型の変更、履歴データのバックフィルは行いません。フィールドソースが同じで、名前の大文字と小文字が完全に一致するカスタム設定は重複できません。ソースが異なれば同じ名前を使用できます。
作成前にソースと name で既存のカスタム設定を確認してください。coverInner=false でも、同名の組み込み設定を隠すことは阻止されません。成功時は need_confirm ではなく、新規作成されたレコードを返します。sysField はサーバー側で処理されるため、Body で sysField を送信しないでください。
書き込みコミット後にキャッシュをクリアします。データベースでは成功していてもキャッシュのクリアに失敗した場合、500 が返ることがあります。失敗時はまず一覧/詳細で作成または変更済みか確認し、直ちに再作成しないでください。同名の同時実行保護により一時的に拒否される場合があります。成功後は設定を読み戻して確認してください。データクエリ表示の反映は、対応するキャッシュとクエリ経路によって異なります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得方法または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得してください。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| aliasI18n.zh | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 主机取得方法または入力方法: zh の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| aliasI18n.en | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: Host取得方法または入力方法: en の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| aliasI18n.zh-hant | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 取得方法または入力方法: zh-hant の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| aliasI18n.id | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 取得方法または入力方法: id の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| aliasI18n.ja | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 取得方法または入力方法: ja の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| aliasI18n.ko | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 取得方法または入力方法: ko の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| descI18n.zh | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 主机取得方法または入力方法: zh の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| descI18n.en | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: Host取得方法または入力方法: en の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| descI18n.zh-hant | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 取得方法または入力方法: zh-hant の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| descI18n.id | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 取得方法または入力方法: id の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| descI18n.ja | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 取得方法または入力方法: ja の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| descI18n.ko | string または null | この言語のみを更新します。空文字列または null を指定すると、この言語の元の値をクリアしますが、実際の表示では他の言語にフォールバックする場合があります。 例: 取得方法または入力方法: ko の表示テキストを入力します。この言語を変更する必要がない場合は、このキーを省略します。 |
|
| alias | string | Y | 新規作成時は必須です。変更時は省略可能で、既存の言語値を保持します。送信時は空でないこと、最大 256 文字です。同じ送信内では aliasI18n.zh が優先されます。 空文字列を許可: False null を許可: False 最大長: 256 例: 主机取得方法または入力方法: コンソールに表示する中国語の別名を入力し、英語およびその他の言語は aliasI18n に設定します。 |
| aliasI18n | object | 任意指定のオブジェクトです。未知の言語キーは無視され、値は文字列を推奨し、null は空文字列に変換されます。送信した言語のみをマージし、他の言語は保持します。互換性のため、alias/aliasEn は zh/en として相互にフォールバックします。 null を許可: False 例: {"en": "Host"}取得方法または入力方法: 実際にサポートされる言語に従って入力し、更新する言語のみを送信します。 |
|
| category | string | 任意指定です。省略時はデフォルトで system になります。変更時に省略した場合も system にリセットされ、元の分類は保持されません。 空文字列を許可: False null を許可: False 選択可能な値: ['system', 'business', 'other'] 例: business取得方法または入力方法: 用途に応じて system/business/other を選択します。 |
|
| coverInner | boolean | 任意指定のブール値です。従来の確認分岐は無効化されています。false でも同名のカスタムフィールドの作成は阻止されず、need_confirm も返されません。一覧では引き続きカスタムが組み込みを上書きしますが、組み込みレコードは変更されません。 null を許可: False 例: false取得方法または入力方法: 現在の実装では省略できます。書き込み後は一覧の coverInner で上書き状態を確認します。 |
|
| desc | string | 任意指定で、最大 3000 文字、空文字列を許可します。変更時に省略した場合は以前の言語値を保持し、明示的な descI18n.zh が優先されます。 空文字列を許可: True null を許可: False 最大長: 3000 例: 主机名称取得方法または入力方法: フィールドの業務上の意味/取得方法を入力し、その他の言語は descI18n に設定します。 |
|
| descI18n | object | 任意指定のオブジェクトです。言語のマージ/クリア/フォールバックは aliasI18n と同じです。OpenAPI は独立した descEn パラメータを受け付けません。英語の説明はこのオブジェクトの en キーに入力します。 null を許可: False 例: {"en": "Host name"}取得方法または入力方法: 言語コードごとに、追加、更新、またはクリアする説明を送信します。 |
|
| fieldSource | string | 任意指定で、省略時は空文字列です。lineage/logging/object/custom_object/keyevent/tracing/rum/security/network/billing および空値をサポートします。変更時に省略すると汎用ソースになり、以前の値は保持されません。 空文字列を許可: True null を許可: False 選択可能な値: ['lineage', 'logging', 'object', 'custom_object', 'keyevent', 'tracing', 'rum', 'security', 'network', 'billing'] 例: logging取得方法または入力方法: 対象のデータカテゴリに応じて選択し、汎用フィールドには明示的に空文字列を入力します。 |
|
| fieldType | string | 宣言は任意ですが、常に明示的に送信することを推奨します。新規作成時に省略すると空文字列で保存され、変更時に省略すると 500 になります。string の場合は unit が強制的に空になり、その他の型では送信された unit が使用されます。過去の number/time/percent は、現在の書き込み API の列挙値として直接送信できません。 空文字列を許可: True null を許可: False 選択可能な値: ['text', 'int', 'float', 'boolean', 'string', 'long'] 例: string取得方法または入力方法: 実際のフィールドに応じて text/int/float/boolean/string/long を選択します。 |
|
| name | string | Y | 必須で、空でなく、最大 256 文字、大文字と小文字を区別します。新規作成時は基本漢字範囲を含む名前を拒否します。変更時は同じ中国語チェックがないため、実際の非中国語フィールド名を維持することを推奨します。 空文字列を許可: False null を許可: False 最大長: 256 例: host取得方法または入力方法: 実際の収集フィールド名を入力します。まずフィールド一覧で同一ソース・同一名の設定を確認してください。 |
| unit | string | 任意指定で、最大 256 文字、デフォルトは空文字列です。変更時に省略するとクリアされ、fieldType=string の場合は何を送信してもクリアされます。この入口では InvalidUnit の業務チェックは実行されません。 空文字列を許可: True null を許可: False 最大長: 256 例: 取得方法または入力方法: 単位説明に従って有効な表示単位識別子を選択し、string の場合は空文字列を入力します。 |
パラメータ補足説明¶
単位情報は単位説明を参照してください。現在、need_confirm による確認は不要です。coverInner は一覧の上書きを制御しません。
3. フィールド管理の使用説明
3.1. フィールド管理はフィールドクエリにフィールド説明を提供します。
以下の関数クエリを実行する際、フィールド説明を返す必要がある場合は、fieldTagDescNeeded(フィールド位置は queries と同じレベル)を true に指定する必要があります。
返される series には value_desc(位置は values、columns と同じレベル)フィールドが追加されます。
| 関数 | フィールドソース/fieldSource |
|---|---|
| SHOW_FIELD(namespace=...) | namespace に応じて対応するフィールドソースを使用します。L は logging、LN は lineage で、専用 SHOW フィールド関数のソースマッピングと互換性があります |
| SHOW_TAG_KEY | "" |
| SHOW_OBJECT_HISTORY_FIELD | "object" |
| SHOW_BACKUP_LOG_FIELD | "logging" |
| SHOW_PROFILING_FIELD | "tracing" |
| SHOW_OBJECT_FIELD | "object" |
| SHOW_LOGGING_FIELD | "logging" |
| SHOW_EVENT_FIELD | "keyevent" |
| SHOW_TRACING_FIELD | "tracing" |
| SHOW_RUM_FIELD | "rum" |
| SHOW_CUSTOM_OBJECT_FIELD | "custom_object" |
| SHOW_CUSTOM_OBJECT_HISTORY_FIELD | "custom_object" |
| SHOW_NETWORK_FIELD | "network" |
| SHOW_SECURITY_FIELD | "security" |
| SHOW_UNRECOVERED_EVENT_FIELD | "keyevent" |
| SHOW_TRACING_METRIC_FIELD | "tracing" |
| SHOW_RUM_METRIC_FIELD | "rum" |
| SHOW_NETWORK_METRIC_FIELD | "network" |
注: SHOW_FIELD_KEY のフィールド説明は、カスタムメトリクス設定と datakit 側の measurements-meta.json を使用します
3.2. フィールド管理はクエリに単位情報を提供します
DQL クエリの単位読み込み(query_data 結果の series に units を追加):
メトリクス データをクエリする場合、読み込まれる単位情報はカスタムメトリクスフィールドのもので、公式メトリクスフィールド(measurements-meta.json)を上書きして算出されます
メトリクス以外 のデータをクエリする場合、読み込まれる単位情報は、フィールド管理で定義された単位です
3.3. フィールド管理が単位情報を提供する場合のクエリ関数の説明
DQL クエリを実行する際、使用する関数が設定された unitWhiteFuncs 関数の範囲内にない場合は単位を付加しません。例: count
unitWhiteFuncs には normal と special の 2 種類の関数があります。special の関数を使用する場合、単位に固定サフィックス /s を付加し、unit = {"unit": unit, "suffix": "/s"} となります
unitWhiteFuncs 関数の説明は以下のとおりです:
unitWhiteFuncs:
normal:
- avg
- bottom
- top
- difference
- non_negative_difference
- distinct
- first
- last
- max
- min
- percentile
- sum
- median
- mode
- spread
- moving_average
- abs
- cumsum
- moving_average
- series_sum
- round
- window
special:
- derivative
- non_negative_derivative
- rate
- irate
4. フィールド同名時の優先順位
4.1. カスタムフィールドは組み込みフィールドより優先されます
4.2. 具体的なソース(fieldSource)を持つフィールドは、汎用フィールドソースより優先されます
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/field_cfg/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"host","alias":"主机","aliasI18n":{"en":"Host"},"fieldType":"string","fieldSource":"logging","category":"business","unit":"","desc":"主机名称","descI18n":{"en":"Host name"},"coverInner":false}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer | レコード番号。API のアドレス指定には使用しません。 |
| content.workspaceUUID | string | 設定の所属ワークスペース。組み込み設定はシステムワークスペースに所属します。 |
| content.status | integer | レコード状態。正常は 0、論理削除は 3。この詳細では有効かつ現在のワークスペースに属するレコードのみを返します。 |
| content.deleteAt | integer | 削除時刻(Unix 秒)。未削除の場合は -1。 |
| content.declaration | object | 現在の呼び出しワークスペースの共通宣言。 |
| content.uuid | string | フィールド設定 UUID。以降の操作ではこの値を使用し、実際のフィールド名ではありません。 |
| content.name | string | 実際のフィールド名。大文字と小文字を区別します。 |
| content.alias | string | 別名。一覧ではリクエスト言語に従って表示され、詳細/作成/変更では互換フィールド値を保持します。 |
| content.aliasEn | string | 互換用の英語別名。中国語にフォールバックする場合があります。 |
| content.aliasI18n | object | 6 言語の元の別名マッピング。空の言語値は、表示が必ず空になることを意味しません。 |
| content.desc | string | 説明。一覧ではリクエスト言語に従って表示され、その他のレスポンスでは互換フィールド値です。 |
| content.descEn | string | 互換用の英語説明。中国語にフォールバックする場合があります。 |
| content.descI18n | object | 6 言語の元の説明マッピング。 |
| content.fieldType | string | 設定されたデータ型。実際に収集されるフィールド型は変更されません。過去の組み込みレコードには、新規作成 Body 以外の値が存在する場合があります。 |
| content.fieldSource | string | 適用ソース。空文字列は汎用設定を表します。 |
| content.unit | string | 表示単位。fieldType=string の保存時は強制的に空になります。 |
| content.sysField | integer | 1 は組み込み、0 はカスタム。組み込み設定はこの API では変更/削除できません。 |
| content.category | string | system はシステムフィールド、business は業務フィールド、other はその他。古いレコードでは空の場合があります。 |
| content.creator | string | 作成元。API Key またはシステム ID の場合があります。 |
| content.updator | string | 更新元。まだ更新されていない場合は空文字列。 |
| content.createAt | integer | 作成時刻(Unix 秒)。 |
| content.updateAt | integer | 更新時刻(Unix 秒)。まだ更新されていない場合は -1 の場合があります。 |
| content.aliasI18n.zh | string | zh 言語の元の別名。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.aliasI18n.en | string | en 言語の元の別名。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.aliasI18n.zh-hant | string | zh-hant 言語の元の別名。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.aliasI18n.id | string | id 言語の元の別名。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.aliasI18n.ja | string | ja 言語の元の別名。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.aliasI18n.ko | string | ko 言語の元の別名。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.descI18n.zh | string | zh 言語の元の説明。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.descI18n.en | string | en 言語の元の説明。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.descI18n.zh-hant | string | zh-hant 言語の元の説明。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.descI18n.id | string | id 言語の元の説明。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.descI18n.ja | string | ja 言語の元の説明。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
| content.descI18n.ko | string | ko 言語の元の説明。未指定の場合は通常空です。一覧表示では言語に応じてフォールバックされます。 |
{
"code": 200,
"content": {
"id": 10,
"uuid": "field_example",
"workspaceUUID": "wksp_example",
"name": "host",
"alias": "主机",
"aliasEn": "Host",
"aliasI18n": {
"zh": "主机",
"en": "Host",
"zh-hant": "主機",
"id": "",
"ja": "",
"ko": ""
},
"desc": "主机名称",
"descEn": "Host name",
"descI18n": {
"zh": "主机名称",
"en": "Host name",
"zh-hant": "主機名稱",
"id": "",
"ja": "",
"ko": ""
},
"fieldType": "string",
"fieldSource": "logging",
"category": "business",
"unit": "",
"sysField": 0,
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落している、またはフィールド値が宣言された検証条件に違反している | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON 形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.FieldCustomNameRepeat | 同一ワークスペース、同一ソース、同一名のカスタム設定が既に存在する、または同時実行の作成/変更が拒否された | 該カスタムフィールド名は既に存在します: {} |
まずソースと名前で既存レコードを確認し、同名の同時送信を避けてください。結果を確認したうえで、変更または名前変更を決定します。 |
| 500 | ft.InternalServerError | 書き込み、コミット後のキャッシュクリア、またはレスポンス組み立てに失敗 | 内部エラー | まず一覧/詳細で送信済み状態を確認し、その後再試行するか決定して、重複作成を避けてください。 |
| 406 | ft.NotSupportedChinese | 新規作成時の name に基本漢字が含まれている | 中国語のフィールド名はサポートされていません | 実際の非中国語フィールド名に変更し、中国語の表示名は alias に入力してください。 |