変更¶
POST /api/v1/field_cfg/{field_uuid}/modify
概要¶
現在のワークスペースのカスタムフィールド設定および多言語表示を変更します。
呼び出し前の準備と使用手順¶
対象ワークスペースの API Key を使用します。この設定は既存のフィールドに表示用のエイリアス、説明、単位、カテゴリを追加するものであり、収集フィールドの作成、実際のデータ型の変更、過去データのバックフィルは行いません。フィールドソースが同じで、名前の大文字と小文字が完全に一致するカスタム設定は重複できません。ソースが異なる場合は同じ名前を使用できます。
変更時は name、fieldType、fieldSource、category、unit をすべて指定する必要があります。これはこれらの設定項目に対する上書きです。alias/desc の多言語データはマージ方式であり、送信されなかった言語は保持され、明示的に空値を指定した場合は表示がフォールバックする可能性があります。変更できるのは現在のワークスペースで有効なカスタムレコードのみで、組み込みレコードは変更できません。
書き込みのコミット後にキャッシュをクリアします。データベースへの書き込みが成功していてもキャッシュのクリアに失敗した場合、500 が返ることがあります。失敗時はまずリストまたは詳細で作成・変更済みかどうかを確認し、直ちに再作成しないでください。同名の同時実行保護により一時的に拒否されることがあります。成功後は読み戻して設定を確認してください。データクエリの表示更新は、対応するキャッシュとクエリ経路に依存します。
パスパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| field_uuid | string | Y | 現在のワークスペースで有効なフィールド設定 UUID。組み込み設定は通常システムワークスペースに属し、リストに表示されても現在のワークスペースで詳細を読み取れるとは限りません。 例: field_example取得または入力方法: フィールドリストから sysField=0 の対象行の uuid を読み取ります。フィールド名は使用しません。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作の権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 | 新規作成時は必須です。変更時は省略可能で、既存の言語値が保持されます。送信時は非空、最大 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 | 任意の 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 はリストの上書きを制御しません。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/field_cfg/field_example/modify' \
-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 またはシステム主体の場合があります。 |
| 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 | ストレージ、キャッシュ、またはレスポンス組み立ての失敗。変更時に fieldType を送信していない場合も未処理の例外が発生する可能性 | 内部エラー | 変更時は有効な fieldType を明示的に送信します。その他の失敗では traceId を保持します。書き込みリクエストの失敗時はまず読み戻して確認し、無闇な再作成を避けます。 |
| 400 | ft.FieldNotFound | UUID が現在のワークスペースに属していない、レコードが存在しない、または削除済み | 指定されたフィールドが見つかりません | 現在のワークスペースのフィールドリストからカスタム設定 UUID を取得します。システムワークスペースの UUID では操作できません。 |
| 406 | ft.NotSupportedModify | 対象の有効なレコードがシステム組み込みフィールドとしてマークされている | システム組み込みフィールドの変更は禁止されています | カスタムフィールドのみを変更します。表示を調整する必要がある場合は、同一ソース・同一名のカスタム設定を作成します。 |