作成¶
POST /api/v1/error_track_rule/add
概要¶
エラー追跡ソースルールを作成します。
呼び出し前の確認と使用手順¶
現在の Key には errorCenter.errorTrackRuleManage が必要で、対象は現在のワークスペースのみです。まず type を決定し、対応するインデックス/アプリケーション/サービス一覧から実際の sources を取得してください。古い例の wsAdmin/acnt_/group_ を流用しないでください。* は全ソースのマーカーであり、[] はワイルドカードではありません。未知のソースは保存に成功しても有効なマッチングが生成されない可能性があります。logging で外部ストレージにバインド済みのアクティブインデックスを明示的に指定した場合は拒否されます。その他のソースには項目ごとの存在性チェックはありません。
作成には名前の一意性チェックと公開された冪等キーがないため、同名の重複リクエストは複数のルールを生成する可能性があります。タイムアウト/500 の場合は、まず一覧で名前/内容を照合し、やみくもに作成をリトライしないでください。
このエントリポイントはルールを保存してデータベースにコミットしますが、このコントローラでは下流の同期呼び出しや過去データの再計算を実行せず、公開/スキャンタスクも返しません。HTTP 200 は今回の保存レスポンスを確認するだけであり、その後のエラー生成や実際の処理範囲は業務データで検証する必要があります。extend には公開された固定の実行用サブキーはないため、自由なオブジェクトを通知/しきい値エンジンとして扱わないでください。返却されるのはコミット前のエンティティスナップショットであり、新規作成時の id は null の可能性があり、sourcesInfo や身元の付加サマリーもありません。詳細を再取得すると最終的な id と rum サマリーを取得できます。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| sources[*] | any | 文字列を推奨します。1 つのインデックス name / appId / サービス service、または * を指定します。元の宣言には要素の型制約がありません。オブジェクト/配列などを保存すると、RUM 一覧のサマリーや下流処理が 500 になる可能性があり、インターフェースによる遮断には依存できません。アカウント/チーム/ロールの UUID ではありません。 例: payment_web取得または入力方法: type=logging の場合はログインデックス一覧から name を取得し、isBindCustomStore=1 を除外します。type=rum の場合はRUM アプリケーション簡易一覧から appId を取得します。type=tracing の場合はサービス一覧から service を取得します。ワイルドカードにはリテラル値 * を使用します。 |
|
| extend.カスタムキー | any | 任意の JSON 値で、オブジェクト/配列/文字列/数値/真偽値/null を使用できます。固定の必須サブキーはありません。資格情報を入れないでください。 例: payment取得または入力方法: 呼び出し元がルールの表示用情報を指定します。 |
|
| desc | string | 省略可能な文字列で、最大 256 文字、空を許可します。作成時に省略すると空になり、変更時に省略してもクリアされ、旧値は保持されません。 空文字列を許可: True null を許可: False 最大長: 256 例: 支払いWebアプリケーションのエラーを追跡取得または入力方法: ルールの保守担当者が用途/範囲の説明を記入します。 |
|
| extend | json | 省略可能な JSON オブジェクトです。ルートが null/配列/文字列の場合は 406 を返します。作成時に省略すると {}、変更時に省略しても {} となり旧値を全体置換し、{} を送信するとクリアされます。この Studio 実装はオブジェクトを保存するだけであり、任意のサブキーからしきい値/通知/正規表現などの実行機能を推測してはいけません。 null を許可: False 例: {"ownerTeam": "payment"}取得または入力方法: 呼び出し元がルールの保守/表示用情報を保存できます。公開された固定の実行用サブ設定はありません。 |
|
| name | string | Y | 必須の文字列で、最大 128 文字です。宣言上は非空を強制していませんが、非空を推奨します。同名でも本インターフェースに一意性チェックはないため、名前を冪等キーにしないでください。変更時も必須で、完全に置き換えられます。 null を許可: False 最大長: 128 例: 支払いWebエラー集約取得または入力方法: 呼び出し元が識別可能なルール名を記入します。 |
| sources | array | 省略可能な配列で、省略すると [] になります。変更時に指定すると全量置換となり、省略してもクリアされます。[] はワイルドカードではないため、すべてのソースを対象にする場合は明示的に ["*"] を指定します。現在、項目ごとの正当な文字列/存在性の検証は行っていないため、クライアントは実際の名前/識別子を使用する必要があります。未知の値が保存できたことはマッチングが有効であることを証明しません。logging で現在アクティブな外部バインドインデックスを指定すると 404 になります。* は外部インデックスを個別に調査しないため、保存成功によって外部インデックスがサポートされることを保証できません。 null を許可: False 例: ["payment_web"]取得または入力方法: type=logging の場合はログインデックス一覧から name を取得し、isBindCustomStore=1 を除外します。type=rum の場合はRUM アプリケーション簡易一覧から appId を取得します。type=tracing の場合はサービス一覧から service を取得します。ワイルドカードにはリテラル値 * を使用します。 |
|
| type | string | Y | 必須で、logging/tracing/rum のいずれかです。変更時も必須で型の変更は可能ですが、新しい型に適した sources を同時に再構築する必要があり、アプリケーション ID/インデックス名/サービス名を混用できません。 null を許可: False 選択可能な値: ['logging', 'tracing', 'rum'] 例: rum取得または入力方法: エラーデータのソースに応じて選択します。logging はログ、tracing は分散型トレーシング、rum はリアルユーザーモニタリング(RUM)です。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/error_track_rule/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"支払いWebエラー集約","desc":"支払いWebアプリケーションのエラーを追跡","type":"rum","sources":["payment_web"],"extend":{"ownerTeam":"payment"}}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 保存されたルールエンティティのスナップショット。 |
| content.id | integer または null | データベースの行 ID。パスによる特定には使用しません。コミット前のスナップショットでは null の可能性があります。 |
| content.uuid | string | エラー追跡ルールの UUID で、issetrule_ プレフィックスが付きます。エラー処理メタデータの isset_ やテレメトリの issue_id ではありません。 |
| content.status | integer | データベースのステータス: 0 有効、2 無効、3 論理削除(読み取り時は 3 を除外)。 |
| content.creator | string | 作成主体の UUID。この公開エントリでは通常、作成に使用した Key リソースの wsak_ です。履歴レコードでは他の主体の場合があり、sys メタデータは自動初期化されません。 |
| content.updator | string | 最後に更新した主体。未更新の場合は空になることがあります。 |
| content.createAt | integer | Unix 秒の作成日時。 |
| content.updateAt | integer | Unix 秒の更新日時。作成後に未更新の場合は通常 -1。 |
| content.deleteAt | integer | Unix 秒の削除日時。未削除の場合は通常 -1。 |
| content.workspaceUUID | string | 現在の Key が属するワークスペース。 |
| content.name | string | ルール名。同名を許可します。 |
| content.desc | string | ルールの説明。 |
| content.type | string | logging/tracing/rum。 |
| content.sources | array | 保存されたソース配列。クライアントは文字列のみを使用すべきです。履歴の非文字列値は許容する必要があります。 |
| content.sources[] | JSON | 通常はインデックス名/appId/サービス名、または *。ロールやアカウントの ID ではありません。 |
| content.extend | object または null | 保存された拡張。通常はオブジェクトとして書き込まれます。履歴値は許容が必要です。 |
| content.extend.カスタムキー | JSON | カスタムの保存値。固定の実行セマンティクスはありません。 |
| content.declaration | object または null | 現在のワークスペースの公開宣言。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "issetrule_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"name": "支払いWebエラー集約",
"desc": "支払いWebアプリケーションのエラーを追跡",
"type": "rum",
"sources": [
"payment_web"
],
"extend": {
"ownerTeam": "payment"
},
"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.JsonFormatError | JSON のトップレベルがオブジェクトでない | 一部の json ファイル形式エラー | ルールオブジェクトを送信してください。 |
| 404 | ft.NotSupportExternalLogIndexCfg | type=logging かつ sources が本ワークスペースのアクティブな isBindCustomStore=1 インデックスに明確に一致 | 外部インデックス設定はサポートされていません | 組み込みインデックスを選択するか、サポートされるソースに変更してください。* で回避して外部インデックスがサポートされると推測しないでください。 |
| 500 | ft.InternalServerError | データベース、履歴オブジェクト、または未処理の保存/レスポンス構築の例外 | 内部エラー | まずルール一覧/詳細を読み戻して実際の保存状況を確認してください。作成には冪等キーがないため、結果不明のリクエストを再送信しないでください。 |