新規作成¶
POST /api/v1/field_cfg/add
概要¶
新しいフィールド管理を作成します。
Body リクエストパラメータ¶
| パラメータ名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| name | string | Y | フィールド名。同一フィールドソース（fieldSource）内で重複不可。 空を許可: False 空文字列を許可: False 最大長: 256 |
| alias | string | Y | フィールドエイリアス 空を許可: False 空文字列を許可: False 最大長: 256 |
| aliasI18n | object | フィールドエイリアスの多言語対応。key は zh/en/zh-hant/id/ja/ko をサポート。 空を許可: False |
|
| unit | string | 単位情報。fieldType が string の場合、単位は空になります。 空を許可: False 最大長: 256 空文字列を許可: True |
|
| fieldType | string | フィールドタイプ 例: time 空を許可: False 空文字列を許可: True 選択可能な値: ['text', 'int', 'float', 'boolean', 'string', 'long'] |
|
| category | string | 属性カテゴリ。システムフィールド（デフォルト選択）、ビジネスフィールド、その他を含む。 空を許可: False 空文字列を許可: False 選択可能な値: ['system', 'business', 'other'] |
|
| fieldSource | string | フィールドソース 例: time 空を許可: False 空文字列を許可: True 選択可能な値: ['logging', 'object', 'custom_object', 'keyevent', 'tracing', 'rum', 'security', 'network', 'billing'] |
|
| desc | string | フィールドの説明 例: ホスト名 空を許可: False 空文字列を許可: True 最大長: 3000 |
|
| descI18n | object | フィールド説明の多言語対応。key は zh/en/zh-hant/id/ja/ko をサポート。 空を許可: False |
|
| coverInner | boolean | フィールド名がシステム組み込みフィールドと同名の場合に上書きするかどうか。true で上書き、false で上書きしない。 例: True 空を許可: False |
パラメータ補足説明¶
1. リクエストパラメータの説明
| パラメータ名 | type | 必須 | 説明 |
|---|---|---|---|
| name | String | 必須 | フィールド名。同一フィールドソース（fieldSource）内で重複不可。 |
| alias | String | 必須 | フィールドエイリアス |
| desc | String | 説明 | |
| unit | String | 単位情報。fieldType が string の場合、単位は空になります。 | |
| fieldType | String | フィールドタイプ | |
| fieldSource | String | フィールドソース。汎用タイプの場合は空文字列を使用。 | |
| coverInner | String | フィールド名がシステム組み込みフィールドと同名の場合に上書きするかどうか。true で上書き、false で上書きしない。 |
単位情報の追加については、 単位説明 を参照してください。
2. レスポンスパラメータの説明
このインターフェースが返す content の内容が need_confirm の場合、同一ソース・同一名の組み込みフィールドが既に存在することを示します。
作成を続行するには、coverInner を true に指定する必要があります。同名の組み込みフィールドは非表示になります。
3. フィールド管理の使用説明
3.1. フィールド管理は、フィールドクエリにフィールド説明を提供します。
以下の関数クエリを実行する際、フィールド説明を返す必要がある場合は、fieldTagDescNeeded（フィールド位置は queries と同じレベル）を true に指定してください。
戻り値の series に value_desc（位置は values、columns と同じレベル）フィールドが追加されます。
| 関数 | フィールドソース/fieldSource |
|---|---|
| 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 'https://openapi.guance.com/api/v1/field_cfg/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Accept-Language: zh' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"name":"test_load","alias":"as_load","fieldType":"float","desc":"temp","fieldSource":"","unit":"","coverInner":false}' \
--compressed
レスポンス¶
{
"code": 200,
"content": {
"alias": "as_load",
"aliasEn": "",
"createAt": 1735628856,
"creator": "wsak_xxx",
"declaration": {
"business": "",
"organization": "default_private_organization"
},
"deleteAt": -1,
"desc": "temp",
"descEn": "",
"fieldSource": "",
"fieldType": "float",
"id": 1791,
"name": "test_load",
"status": 0,
"sysField": 0,
"unit": "",
"updateAt": -1,
"updator": "",
"uuid": "field_0f95016f7254494da088d878ce586477",
"workspaceUUID": "wksp_05adf2282d0d47f8b79e70547e939617"
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-5E004BC0-E1E0-459A-8843-6FECBF0353DF"
}