インポート¶
POST /api/v1/pipeline/import
概要¶
Pipeline テンプレートを一括追加し、デフォルト置換の確認と構文検証を処理します。
呼び出し前の確認と使用手順¶
エクスポートした pipelines 配列を使用し、対象ワークスペースに照らしてソースを確認してください。同じカテゴリの名前、または同じ category/type で完全一致する source が競合する項目は直接スキップされ、上書きされません。fail_count にはスキップ数が含まれるため、すべてをエラーと解釈しないでください。* または ? を含む source は完全一致の競合比較の対象外です。同じバッチ内で同じカテゴリかつ同じ名前の候補はコンパイル前チェックで拒否されます。同じバッチ内で同じ category/type に複数の asDefault=1 を指定しないでください。
confirm が返された場合、バッチ全体は書き込まれません。確認後に isForce=true で再試行してください。強制的なデフォルト置換は、すべての候補の構文検証が通過するまで延期されます。すべての候補スクリプトは共通の依存関係ビューでコンパイルされ、後続の候補を参照できます。構文エラーがある場合、バッチ全体はコミットされません。現在のインポートでは isDisable は適用されず、追加に成功したものはデフォルトで有効になります。履歴バージョン番号は保持されません。rum/llm のインポートではテンプレートの source 関係を引き継ぎ、単体追加時の extend による直積再構築は行いません。同一バージョンのエクスポート済みテンプレートを直接使用することを推奨し、内部関連を手作業で組み立てないでください。
examples の各項目は単一の JSON 値をエンコードし、testData は旧形式で配列全体をエンコードします。現在のインポートでは、公開 add のサンプル配列/項目ごとの 20KiB 検証を完全には再利用していないため、呼び出し側でサンプルのサイズと型を制御する必要があります。内部テンプレートのフィールドは項目ごとに強制されないため、不正な形式の場合は 500 になることがあります。
保存時には同期的に構文を検証し、設定/バージョンを更新します。実際の収集またはセンター処理への反映は、後続の設定取得とデータフローに依存します。過去のデータは再実行されず、解析サンプルの結果も返されません。変更前に詳細をバックアップし、エラー/タイムアウト後はまず現在のバージョンを読み戻してから再試行してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| pipelines[*] | json | 追加するテンプレート。既存の同名または同一ソースは上書きしません。列挙されていないフィールドには依存しないでください。 例: {"name": "production_parser", "type": "local", "category": "logging", "asDefault": 0, "enableByLogBackup": 0, "source": ["nginx"], "isDisable": false, "content": "YWRkX2tleSgiZW52IiwgInByb2R1Y3Rpb24iKQ==", "examples": [{"data": "eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}], "dataType": "json", "extend": {"loggingIndex": "default"}}取得または入力方法: エクスポート済みテンプレートを基準とし、対象の名前とソースを置き換えます。 |
|
| pipelines[*].name | string | 必須。最大 256 カウント単位(ASCII/半角カタカナは 1、その他の文字は 2)。英数字、アンダースコア、中国語 U+4e00..9fa5、およびハイフンを使用できます。空でないことを推奨します。同じ category では、local/central が異なる場合や既存項目が無効な場合でも重複は許可されません。入力ログの source ではありません。 例: production_parser取得または入力方法: 業務で定義するファイル名。まず Pipeline リスト で同じカテゴリの未削除の名前を確認します。 |
|
| pipelines[*].type | string | 必須。local/central。Synthetic テスト(dialtesting)の追加/変更では central のみ使用できます。ワークスペースのバージョンによって central が制限される場合があります。変更すると元の実行タイプが置き換わります。 例: local取得または入力方法: ローカルコレクターで処理する場合は local、プラットフォームのセンターで処理する場合は central を選択し、実際のデータ入口を確認します。 |
|
| pipelines[*].category | string | 必須。lineage/logging/object/custom_object/network/tracing/rum/llm/agent_monitor/security/keyevent/metric/profiling/dialtesting/cloud_billing。billing は過去互換の値です。変更によりカテゴリを変更できますが、スクリプト、source、extend を併せて確認する必要があります。 例: logging取得または入力方法: 対象のデータドメインと収集設定に応じて選択します。 |
|
| pipelines[*].source | array | 任意。デフォルトは []。変更時に省略すると、すべてのソース関係が削除されます。* または ? を含むソースは完全一致の一意性競合チェックの対象外であり、すべてのマッチングの実行時動作を保証するものではありません。通常の完全一致ソースは、同じ category/type 内で他の未削除 Pipeline が占有することはできません。rum/llm の追加/変更ではこの配列は無視され、extend.appID と measurement が使用されます。 例: ["nginx"]取得または入力方法: 対応する収集データの source またはソースセレクターから値を取得します。Pipeline 名ではありません。ログの場合は実際のログ source を参照できます。 |
|
| pipelines[*].source[*] | string | 空でない文字列を推奨します。配列は項目ごとに厳密には検証されません。無関係なデータドメインを混在させないでください。 例: nginx取得または入力方法: 単一の実際のソース識別子、または収集側でサポートされるワイルドカードパターン。 |
|
| pipelines[*].content | string | 必須。base64 文字列。追加時はデコード後に空でない必要があります。デコードしたスクリプト全文は、UI 文字カウント ≤1048576 と UTF8 バイト数 ≤1048576 の両方を満たす必要があります。BMP の非 ASCII は 2、補助文字は 4 としてカウントされます。いずれかが上限を超えると ft.ContextExceedLimit になります。保存時にはサンプルなしで同期的にコンパイルし、同じカテゴリで有効なスクリプトの参照を確認します。成功しても、実データでのデバッグ通過や反映済みを意味するものではありません。 例: YWRkX2tleSgiZW52IiwgInByb2R1Y3Rpb24iKQ==取得または入力方法: まず UTF8 の Pipeline スクリプトを作成し、その後標準 base64 エンコードを行います。例はデコードすると add_key("env", "production") になります。 |
|
| pipelines[*].dataType | string | 任意。デフォルトは line_protocol。line_protocol/json/message をサポートします。変更時に省略すると line_protocol に戻ります。category ではありません。空文字列は互換として宣言されていますが、サポートされる値を明示的に選択してください。 例: json取得または入力方法: testData のサンプルとスクリプト入力に応じて選択します。 |
|
| pipelines[*].asDefault | integer | 任意。デフォルトは 0。0/1 のみを指定することを推奨します。既にデフォルトが存在し、isForce がない場合は HTTP 200 で confirm 配列が返され、今回の対象設定は保存されません。作成/変更の成功として扱わないでください。 例: 0取得または入力方法: 同じ category/type のフォールバックルールにする場合は 1、それ以外は 0。 |
|
| pipelines[*].enableByLogBackup | integer | 任意。デフォルトは 0。0/1 を推奨します。このフラグを保存しても、既存の転送データが自動的に再実行されることは保証されません。 例: 0取得または入力方法: ルールで転送データを処理する必要がある場合は 1。実際のデータ転送チェーンでサポートを確認してください。 |
|
| pipelines[*].extend | json | 任意。デフォルトは {}。変更時は全体を置換し、マージは行いません。rum/llm は appID×measurement の組み合わせでソース関係を生成します。未知のサブフィールドは公開検証で拒否されます。 例: {"loggingIndex": "default"}取得または入力方法: カテゴリと既存の詳細に基づいて、以下の宣言フィールドを構成します。 |
|
| pipelines[*].extend.appID | array | rum/llm では measurement と同時に空でない配列を指定する必要があります。両方とも空の場合は専用ソースなしにできます。appID があり measurement がない場合はパラメータ不足としてエラーになります。 例: ["appid_example"]取得または入力方法: 対応する RUM/LLM アプリケーション管理から実際の appId を取得します。 |
|
| pipelines[*].extend.measurement | array | rum/llm では appID と直積の組み合わせを行います。measurement があるのに appID がない場合はパラメータ不足としてエラーになります。保存時には、各アプリケーション/measurement にデータが存在するかは検証されません。 例: ["view"]取得または入力方法: そのアプリケーションの実データの measurement から取得します。たとえば RUM の view/action などで、実際のカテゴリに応じて入力します。 |
|
| pipelines[*].extend.loggingIndex | string | 任意。ログインデックスのエコーバック用フィールド。デフォルトでは値を補完しません。変更時に省略すると extend とともに削除されます。source 配列ではありません。 例: default取得または入力方法: ログインデックスリスト から適用可能なインデックス識別子を取得します。 |
|
| pipelines[*].extend.ifAiCreate | boolean | 任意。エコーバック用で、AI タスクをトリガーしません。 例: false取得または入力方法: AI 支援で生成されたかどうかを記録します。このマークが不要な場合は省略できます。 |
|
| pipelines[*].extend.aiTargetStructure | string | 任意の文字列。保存とエコーバックのみで、本 API はスクリプトを生成しません。 例: 取得または入力方法: AI 生成時の対象構造の説明。不要な場合は省略できます。 |
|
| pipelines[*].extend.exampleSource | string | 任意のエコーバック。source の関連付けを代替しません。 例: nginx取得または入力方法: サンプルソースの表示値。実際の source と対応している必要があります。 |
|
| pipelines[*].extend.exampleType | string | 任意のエコーバック文字列。サーバー側で固定の列挙値は提供されません。 例: custom取得または入力方法: サンプルタイプの表示値。クライアントの業務で定義します。 |
|
| pipelines[*].extend.appID[*] | string | 空でない文字列を推奨します。 例: appid_example取得または入力方法: アプリケーション設定から単一の appId を取得します。 |
|
| pipelines[*].extend.measurement[*] | string | 空でない文字列を推奨します。 例: view取得または入力方法: 実際の measurement の元の名前。 |
|
| pipelines[*].isDisable | boolean | エクスポート時の元の状態。現在の公開 import ではこのマークは適用されず、インポート後はデフォルトで有効になります。 例: false取得または入力方法: エクスポート済みテンプレートの対応するフィールドから取得します。設定の意味は本ページの説明と同じです。 |
|
| pipelines[*].examples | array<object> |
旧 testData より優先されます。オブジェクト/文字列の正当な JSON エンコードを提供することを推奨します。不正な JSON のデコード内容は、元のテキストではなく null として保存される可能性があります。 例: [{"data": "eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}]取得または入力方法: 各サンプルはまず JSON 値にシリアライズし、その後 UTF8 base64 にします。 |
|
| pipelines[*].examples[*] | json | 空でないオブジェクトを推奨します。 例: {"data": "eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}取得または入力方法: 単一の {data:base64} オブジェクト。 |
|
| pipelines[*].examples[*].data | string | 正当な JSON 値のエンコードであり、サンプル配列全体ではありません。追加時の testData とはエンコード階層が異なります。 例: eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ==取得または入力方法: 例は単一の JSON オブジェクトの UTF8 base64 です。 |
|
| pipelines[*].testData | string | 任意。旧形式。examples が存在する場合は優先されます。デコード時の None を防ぐため、省略ではなく W10= を使用してください。 例: W10=取得または入力方法: 古いテンプレートに examples がない場合にのみ使用し、サンプル配列全体をエンコードします。 |
|
| isForce | boolean | 任意。デフォルトは false。デフォルト競合の確認のみに使用し、構文、ソース、名前、バージョンなどの検証をスキップすることはできません。強制置換では元のデフォルトを非デフォルトに変更し、そのバージョンをアーカイブします。 null を許可: False 例: false取得または入力方法: content.confirm を受信した後、元のデフォルト Pipeline の置換を確認してから true に設定します。 |
|
| pipelineType | string | Y | 必須。logging/all。logging はログ以外をスキップしますが、一部の制限/確認検出はカテゴリのスキップ前に実行されます。 選択可能な値: ['logging', 'all'] 例: all取得または入力方法: 複数カテゴリのインポートを管理する場合は all、ログのみをインポートする場合は logging。 |
| pipelines | array | Y | 必須の配列。空配列の場合は成功し、統計はゼロになります。各項目はテンプレートオブジェクトで、内部では完全なフィールド宣言検証は実行されません。統一レスポンスをそのまま渡さないでください。 null を許可: False 例: [{"name": "production_parser", "type": "local", "category": "logging", "asDefault": 0, "enableByLogBackup": 0, "source": ["nginx"], "isDisable": false, "content": "YWRkX2tleSgiZW52IiwgInByb2R1Y3Rpb24iKQ==", "examples": [{"data": "eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}], "dataType": "json", "extend": {"loggingIndex": "default"}}]取得または入力方法: export レスポンスの content.pipelines から配列を取得します。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/pipeline/import' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"pipelineType":"all","isForce":false,"pipelines":[{"name":"production_parser","type":"local","category":"logging","asDefault":0,"enableByLogBackup":0,"source":["nginx"],"isDisable":false,"content":"YWRkX2tleSgiZW52IiwgInByb2R1Y3Rpb24iKQ==","examples":[{"data":"eyJtZXNzYWdlIjoiZXhhbXBsZSBsb2cifQ=="}],"dataType":"json","extend":{"loggingIndex":"default"}}]}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.success_count | integer | 追加に成功した候補数。 |
| content.fail_count | integer | 入力数から成功数を引いた値。スキップ項目を含みます。項目ごとの理由はありません。 |
| content.declaration | object | 共通宣言。 |
| content.confirm | array<string> |
デフォルト競合時に通常のエンティティの代わりに返され、置換の確認が必要なカテゴリを列挙します。この分岐では今回の対象は保存されません。 |
| content.confirm[] | string | 単一のカテゴリ。 |
| content.pl_errors | array<object> |
ft.PipelineSyntaxError エラーの content でのみ返されるコンパイルエラーの配列。 |
| content.pl_errors[].error | string | コンパイルエラーの説明。 |
| content.pl_errors[].pos_chain | array<object> |
参照/位置チェーン。 |
| content.pl_errors[].pos_chain[].file | string | ファイル名。 |
| content.pl_errors[].pos_chain[].ln | integer | 負でない位置インデックス。コンパイラーにより定義されます。調査時は元の値を保持してください。 |
| content.pl_errors[].pos_chain[].col | integer | 負でない位置インデックス。コンパイラーにより定義されます。調査時は元の値を保持してください。 |
| content.pl_errors[].pos_chain[].pos | integer | 負でない位置インデックス。コンパイラーにより定義されます。調査時は元の値を保持してください。 |
{
"code": 200,
"content": {
"success_count": 1,
"fail_count": 0,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
デフォルトの確認待ち:
{
"code": 200,
"content": {
"confirm": [
"logging"
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、および共通リクエストエラーについては、共通エラー定義 を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析に失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 406 | ft.InvalidBase64 | スクリプト/テストサンプルがデコード可能な UTF8 base64 でない。追加時の testData が省略された場合も発生することがあります | 無効な base64 内容 | content と testData を完全に提供し、UTF8 の後に base64 エンコードしてください。 |
| 406 | ft.ContextExceedLimit | スクリプトが UI 文字カウントまたは UTF8 バイト数 1MiB を超えている、または add/modify の単一テストサンプルが過去の長さ制限を超えている | テキスト内容が制限を超えています。制限は {} 文字です | スクリプト/単一サンプルを縮小し、message に示された単位を確認してください。 |
| 406 | ft.PipelineSyntaxError | サンプルなしの同期コンパイルでスクリプトまたは参照の構文エラーが返された | Pipeline スクリプトの構文エラーです。エラー位置を確認してください | content.pl_errors の error と pos_chain に従って位置を特定して修正し、再試行してください。 |
| 400 | ft.PipelineNameExists | 同じバッチ内で同じカテゴリの候補スクリプト名が重複 | 同名の Pipeline が既に存在します | まずテンプレート名を重複排除してください。 |
| 403 | ft.ForbiddenFreeEditionWorkspace | いずれかの候補の type がワークスペースのバージョンに適合しない | 無料プランのワークスペースではこの機能はサポートされません。商用プランにアップグレードすると制限を解除できます | 対象の実行方式を調整してください。 |
| 403 | ft.ForbiddenFreeWKSPCentralPipeline | 無料/体験版ワークスペースで central をインポート | 無料プランのワークスペースではセンター pipeline 設定はサポートされません | ワークスペースのバージョンがサポートしていることを確認してください。 |
| 500 | ft.InternalServerError | 同期コンパイルサービスが利用不可/タイムアウト/形式異常(内部の PipelineValidationUnavailable は最終的に統一的にラップされる)、データベース、構造エラー、またはコミット後のフォーマット失敗 | 内部エラー | 後で再試行する前に現在の設定とバージョンを読み取り、既に保存されているか確認してください。継続的に失敗する場合は traceId を提供してください。 |