自動検出設定を作成¶
POST /api/v1/issue_auto_discovery/add
概要¶
イベント集約に基づく Issue 自動検出設定を作成します。
呼び出し前の注意と使用手順¶
本モジュールは従来のインシデントの Issue 自動検出設定であり、インシデントセンターの Incidents オンコール/自動集約でも、エラーセンターの ErrorTrack ルールでもありません。現在公開されている書き込みで dqlNamespace に指定できるのは keyevent のみです。rum/tracing の旧サンプルは現在の宣言に適合しません。バックエンドで issueUpgrade=true に移行済みのワークスペースでは、この v2 自動検出タスクはスキップされます。設定の成功をもって、そのワークスペースで新しい Issue が生成されることを保証することはできません。
権限は trace.issueDiscovery/rum.issueDiscovery/anomaly.issueDiscovery のいずれかに一致する必要があります。ルールの name と生成される Issue の config.name は別々のフィールドです。every は 300/600/900/1800/3600 のみです。60 は旧列挙に存在しますが、事前の最小値チェックで拒否されます。dimensions には明示的に空でないフィールド名を指定し、config には description、channelUUIDs、extend.text を明示的に指定してください。そうしない場合、保存に成功してもタスクがキー欠落や無効なクエリにより失敗する可能性があります。
ルール名はワークスペース内で一意ですが冪等キーはありません。結果が不明な場合はまず名前と内容を確認し、重複作成しないでください。
config.extend.manager は正規化されます。未知のアカウント/対象はサイレントに除外される可能性があります。明示的な null は宣言上許可されていますが、現在の監査/処理では直接 .get するため 500 になります。渡さないでください。dutyPerson を指定した場合は従来のインシデント通知スケジュールを使用し、インシデントセンターのオンコールではありません。{{変数}} はグループタグ/集約 count の word キーによってのみ置換され、未知の変数はそのまま残ります。任意のテンプレートコードは実行されません。
設定の保存ではクエリを即時実行したり、生成タスクを返したりしません。スケジュールは Asia/Shanghai のカレンダーに合わせた周期で、直前の every 秒のウィンドウを処理します。タスクキューやクエリの所要時間により遅延する場合があります。keyevent は monitor イベントから集約し、dimensions に従って最大 1000 個のグループを生成します。広範囲の完全なカバレッジは保証しません。グループディメンションをソートした JSON が重複識別子を生成し、ルール UUID はその識別子に含まれません。複数のルールが同一ワークスペースで同じディメンション値を持つ場合、同じ既存 Issue に関連付けられる可能性があります。ディメンション/フィルタの変更はグループ結果を変える可能性があります。これをルールごとに独立し、決して交差しない Issue 集合とみなさないでください。Open/Pending の場合は返信を追加し、Resolved は再オープンして回帰し、Closed は再利用しません。履歴の Working ブランチは実際の実装に従って処理され、作業中の完全な分離は保証しません。通知は非同期であり、HTTP 200 はデータクエリの成功/新しい Issue の生成/通知の到達を意味しません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| dimensions[*] | string | 単一のフィールド名文字列です。元の宣言では子項目を制約していません。文字列以外は同期監査資料の結合時に 500 になります:add は通常コミット前に失敗し、modify は初回コミット後に失敗する場合があります。文字列でもフィールドが存在しない場合は、バックグラウンドのクエリ時に失敗する/データがない可能性があります。バッククォートや完全なクエリ断片をフィールド名として使用しないでください。 例: service取得または入力方法: イベントのフィールド/タグ名。対象データすべてにそのフィールドがあることを確認してください。 |
|
| config.channelUUIDs[*] | string | 単一の有効なチャンネル UUID です。ディメンションフィールド/チーム UUID ではありません。未知または無効の場合は 404 になります。 例: chan_example取得または入力方法: 現在のワークスペースのチャンネル簡易一覧の uuid。 |
|
| config.extend.text | string | 明示的な文字列を推奨します。タスクが読み取ってテンプレート置換を行うため、欠落/文字列以外は非同期で失敗する可能性があります。config.description とはそれぞれ別に保存されるテキストフィールドです。 例: サービス{{service}}が{{count}}件のイベントを検出取得または入力方法: dimensions のタグおよび集約 count に合わせて Issue 本文テンプレートを構成します。 |
|
| config.extend.manager | array | オプションの担当者文字列配列です。有効な acnt_/本ワークスペースのチーム/メールアドレス/dutyPerson は保持されます。未知のアカウント/未知の値はサイレントに除外される可能性があり、項目ごとのエラーは保証されません。無料プランのワークスペースは外部メールアドレスをサポートせず、400 になる場合があります。担当者が欠落すると未割り当てのエスカレーションフローに入る可能性があります。 例: []取得または入力方法: ワークスペースメンバーから acnt_ を、チーム一覧から group_ を取得します。またはメンバー/許可された外部メールアドレスを使用します。従来のインシデントの本日のオンコール担当者が必要な場合は、リテラル値 dutyPerson を使用します。設定は通知スケジュールを参照してください。 |
|
| config.extend.manager[*] | string | 有効な主体、メールアドレス、または dutyPerson を 1 つ指定します。文字列以外は文字列 startswith の処理時に 500 になる可能性があります。 例: acnt_example取得または入力方法: ワークスペースメンバーから acnt_ を、チーム一覧から group_ を取得します。またはメンバー/許可された外部メールアドレスを使用します。従来のインシデントの本日のオンコール担当者が必要な場合は、リテラル値 dutyPerson を使用します。設定は通知スケジュールを参照してください。 |
|
| config.extend.conditionsInputFilters | any | オプションの任意 JSON で、履歴 Issue/通知イベントからのジャンプ時に補足フィルタを表示するためのものです。実際のクエリは引き続きトップレベルの conditions を使用するため、このキーだけを変更して代用することはできません。 例: {}取得または入力方法: 従来のインシデント条件エディタが提供する表示構造を使用できます。 |
|
| config.extend.variable | json | リクエストで入力することは推奨しません。タスクが実際のクエリ列でこのオブジェクトを上書きします。通常 count はウィンドウ内の件数です。 例: {"count": 8}取得または入力方法: 生成タスクの実行時に集約変数を計算します。 |
|
| config.extend.variable.count | integer | 実行時の出現回数です。呼び出し元の入力は信頼できる固定値として有効になりません。 例: 8取得または入力方法: バックグラウンドで本ウィンドウの count(*) クエリにより計算されます。 |
|
| config.extend.tags | json | リクエストで入力することは推奨しません。タスクが実際のグループタグで上書きし、Issue の重複排除およびテンプレート変数に使用されます。 例: {"service": "payment"}取得または入力方法: 生成タスクがグループタグから取得します。 |
|
| config.extend.tags.フィールド | any | 動的な JSON タグ値です。呼び出し元が手入力した値によってグループ生成を固定することはできません。 例: payment取得または入力方法: dimensions に対応するイベントタグ値から取得します。 |
|
| config.extend.channelUUIDs | array | 実行時に有効な設定チャンネルで上書きされます。この拡張フィールドを config.channelUUIDs の代用にしないでください。 例: []取得または入力方法: タスクが config.channelUUIDs に従って現在有効なチャンネルを絞り込んだ後に書き込みます。 |
|
| config.extend.channelUUIDs[*] | string | 実行時に有効なチャンネル識別子を 1 つ指定します。 例: chan_example取得または入力方法: 現在のワークスペースで有効なチャンネル uuid。 |
|
| config.extend.カスタムキー | any | 任意の JSON 保存値です。本ページで公開されている追加の実行保証はありません。認証情報を入れないでください。 例: value取得または入力方法: 呼び出し元の業務表示用拡張。 |
|
| conditions | string | オプションの文字列で、フィルタ式のみです。完全な DQL/JSON ではありません。作成時に省略すると空、変更時に省略すると保持、空だとクリアされます。現在の保存では DQL を解析しないため、構文/フィールドの有効性は保証されず、非同期タスクの失敗が今回のインターフェースエラーになることもありません。エンティティ列は 48 文字ですが、宣言に長さ制限はありません。短い式を使用し、デプロイ時の列制限を管理者に確認することを推奨します。 空文字列を許可: True null を許可: False 例: `df_status` = 'error'取得または入力方法: 対象 monitor イベントの実際のフィールドから DQL フィルタ条件を構成します。クエリツールで同じ時間範囲を使用して事前に検証できます。 |
|
| config | json | Y | 必須オブジェクトです。変更時は毎回全体を置換し、再帰的にマージしません。許可されるのは name/level/channelUUIDs/description/extend の 5 つの宣言済みキーのみです。後続タスクの確実な実行のため、オプションであっても description、channelUUIDs 配列、extend オブジェクトおよび extend.text 文字列を明示的に指定することを推奨します。欠落すると保存には成功してもタスクが失敗する可能性があります。 null を許可: False 例: {"name": "サービス{{service}}アラート", "description": "本ウィンドウの{{count}}件のイベント", "channelUUIDs": [], "extend": {"text": "サービス{{service}}が{{count}}件のイベントを検出", "manager": []}}取得または入力方法: 本ページのテンプレート設定に従って Issue のタイトル、本文、チャンネル、担当者を生成します。 |
| config.channelUUIDs | array | オプションのチャンネル UUID 配列です。明示する項目は現在有効である必要があります。常に [] または有効な配列を渡すことを推奨します。省略しても保存は可能ですが、タスクが None を走査して失敗する可能性があります。タスクはデフォルトのチャンネル関連付けを自動的に補います。保存自体は、[] の場合でもワークスペースに少なくとも 1 つの有効なチャンネルが存在することを要求します。 null を許可: False 例: []取得または入力方法: チャンネル簡易一覧から現在のワークスペースの有効な chan_ UUID を取得します。 |
|
| config.description | string | 宣言上はオプションの文字列ですが、後続タスクがこのキーを直接読み取るため、常に明示的に指定することを推奨します(空文字列でも可)。変更時は config が全体置換となるため、サブキーを省略しても旧値は保持されません。 null を許可: False 例: 本ウィンドウの{{count}}件のイベント取得または入力方法: 同じテンプレート変数を使用して Issue の説明を構成します。 |
|
| config.extend | json | オプションのオブジェクトまたは null です。実際の作成/変更の監査資料では extend.get を直接行うため、明示的な null は 500 になります。作成時は通常コミット前に、変更時の履歴監査ではコミット後に失敗する可能性があります。常に text を含むオブジェクトを渡すことを推奨します。省略した場合も保存後にタスクが extend/text の欠落で失敗する可能性があります。オブジェクトが出現すると全体置換となるため、任意の子値は有効な構造を保つ必要があります。 null を許可: True 例: {"text": "サービス{{service}}が{{count}}件のイベントを検出", "manager": []}取得または入力方法: Issue を作成 の表示拡張を参照し、本ページで確認済みの消費フィールドに従ってください。 |
|
| config.level | string | オプションのレベル UUID または空文字列です。空でない場合は現在有効である必要があり、そうでなければ 406 になります。省略するとレベルを指定しません。インシデントセンターのレベル UUID の汎用代替フィールドではありません。 空文字列を許可: True null を許可: False 例: system_level_0取得または入力方法: Issue レベル一覧から uuid を取得します。バックエンドでグローバルレベルが有効になっている場合は管理者の設定が優先されます。 |
|
| config.name | string | Y | 必須の文字列で最大 256 文字です。Issue タイトルテンプレートであり、ルールの name とは異なります。{{service}}/{{count}} などの word 変数名をサポートし、未知の変数はそのまま残ります。任意の Python/Jinja 式はサポートせず、ドット/ハイフンを含むフィールドは置換が保証されません。 null を許可: False 最大長: 256 例: サービス{{service}}アラート取得または入力方法: dimensions のフィールドおよび集約変数 count に合わせてタイトルテンプレートを構成します。 |
| description | string | オプションの文字列で、空を許可します。作成時に省略すると空、変更時に省略すると保持、明示的に空にするとクリアされます。Issue 本文テンプレートとしては使用されません。 空文字列を許可: True null を許可: False 例: サービス単位で本番アラートを集約取得または入力方法: 呼び出し元がルールの用途説明を記入します。 |
|
| dimensions | array | オプションの配列で、出現する場合は少なくとも 1 項目です。作成時に省略すると [] として保存されますが、タスクが構築する by 句が無効になる可能性があるため、常に空でない実フィールドを指定することを推奨します。変更時に省略すると保持され、[] は事前に 406 となるためクリアには使用できません。フィールド名であり、チャンネル UUID ではありません。フィールドの順序/集合はグループクエリに影響し、df_label は集合に従って集約されます。 null を許可: False 最小長: 1 例: ["service"]取得または入力方法: イベントの実際のタグフィールドから、グループ化と重複排除に使用するフィールド名(service、host、df_label など)を選択します。 |
|
| dqlNamespace | string | Y | 必須で、公開されている唯一の列挙値は keyevent です。rum/tracing ではなく、履歴のエンティティ/サンプルが他の値を許可していたからといって渡すことはできません。 null を許可: False 選択可能な値: ['keyevent'] 例: keyevent取得または入力方法: 現在公開されている範囲では固定で keyevent イベント範囲を使用します。 |
| every | integer | Y | 必須の整数で、300/600/900/1800/3600 のみです。旧列挙に 60 が含まれていますが最小値 300 も同時に有効であるため、60 は公開ルートで 406 となり、1 分は選択できません。 null を許可: False 選択可能な値: [60, 300, 600, 900, 1800, 3600] $maxValue: 3600 $minValue: 300 例: 300取得または入力方法: 検出遅延とクエリ量に応じて周期の秒数を選択します。 |
| name | string | Y | 必須の文字列で最大 256 文字です。宣言では空でないことを強制していませんが、空でないことを推奨します。同じワークスペース内で削除されていないルール名は重複できません。変更時も必須です。これはルール名であり、生成される Issue のタイトルではありません。 null を許可: False 最大長: 256 例: 本番イベント自動検出取得または入力方法: 保守担当者がワークスペース内で一意のルール名を記入します。 |
パラメータ補足説明¶
現在の公開範囲は keyevent です。設定の保存、定時実行、通知の到達は異なる段階であり、パラメータと完全なレスポンス/エラー境界は以下を参照してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/issue_auto_discovery/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"生产事件自动发现","description":"按服务聚合生产告警","dqlNamespace":"keyevent","every":300,"conditions":"`df_status` = '"'"'error'"'"'","dimensions":["service"],"config":{"name":"服务{{service}}告警","description":"本窗口{{count}}条事件","channelUUIDs":[],"extend":{"text":"服务{{service}}发现{{count}}条事件","manager":[]}}}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | コミット前の設定スナップショットです。作成/更新の識別情報サマリーは付かず、生成済みの Issue/実行結果も含みません。 |
| content.id | integer または null | データベースの行 ID です。パスによる特定には使用しません。コミット前のスナップショットでは null の場合があります。 |
| content.uuid | string | 自動検出ルールの UUID で、iatdc_ プレフィックスが付きます。 |
| content.status | integer | 0 有効、2 無効、3 ソフト削除。読み取り時は 3 を除外します。 |
| content.creator | string | 作成主体の UUID で、現在の公開エントリでは通常 wsak_ です。 |
| content.updator | string または null | 更新主体です。作成スナップショットでは空または null の場合があります。 |
| content.createAt | integer | Unix 秒の作成時間。 |
| content.updateAt | integer または null | Unix 秒の更新時間です。コミット前の作成スナップショットでは null の場合があり、以降のデータベースのデフォルト/更新値は -1 または実際の時間になる場合があります。 |
| content.deleteAt | integer | Unix 秒の削除時間です。未削除の場合は通常 -1 です。 |
| content.workspaceUUID | string | 現在の Key が属するワークスペース。 |
| content.name | string | ルール名。 |
| content.description | string | ルールの説明であり、Issue 本文テンプレートではありません。 |
| content.dqlNamespace | string | 現在の公開書き込みは keyevent です。履歴レコードは他の名前空間である場合がありますが、公開インターフェースで書き戻せることを意味しません。 |
| content.every | integer | 周期の秒数。 |
| content.conditions | string | 保存済みの DQL フィルタ式です。実行成功が検証済みであることを意味しません。 |
| content.dimensions | array<string> |
グループ化フィールド名の配列です。履歴の誤った型に対しては寛容に扱う必要があります。 |
| content.dimensions[] | string | イベントのフィールド名 1 つ。 |
| content.config | object | 生成される Issue の定義テンプレート。 |
| content.config.name | string | 必須の文字列で最大 256 文字です。Issue タイトルテンプレートであり、ルールの name とは異なります。{{service}}/{{count}} などの word 変数名をサポートし、未知の変数はそのまま残ります。任意の Python/Jinja 式はサポートせず、ドット/ハイフンを含むフィールドは置換が保証されません。 |
| content.config.level | string | オプションのレベル UUID または空文字列です。空でない場合は現在有効である必要があり、そうでなければ 406 になります。省略するとレベルを指定しません。インシデントセンターのレベル UUID の汎用代替フィールドではありません。 |
| content.config.channelUUIDs | array | オプションのチャンネル UUID 配列です。明示する項目は現在有効である必要があります。常に [] または有効な配列を渡すことを推奨します。省略しても保存は可能ですが、タスクが None を走査して失敗する可能性があります。タスクはデフォルトのチャンネル関連付けを自動的に補います。保存自体は、[] の場合でもワークスペースに少なくとも 1 つの有効なチャンネルが存在することを要求します。 |
| content.config.channelUUIDs[] | string | 単一の有効なチャンネル UUID です。ディメンションフィールド/チーム UUID ではありません。未知または無効の場合は 404 になります。 |
| content.config.description | string | 宣言上はオプションの文字列ですが、後続タスクがこのキーを直接読み取るため、常に明示的に指定することを推奨します(空文字列でも可)。変更時は config が全体置換となるため、サブキーを省略しても旧値は保持されません。 |
| content.config.extend.text | string | 明示的な文字列を推奨します。タスクが読み取ってテンプレート置換を行うため、欠落/文字列以外は非同期で失敗する可能性があります。config.description とはそれぞれ別に保存されるテキストフィールドです。 |
| content.config.extend.manager | array | オプションの担当者文字列配列です。有効な acnt_/本ワークスペースのチーム/メールアドレス/dutyPerson は保持されます。未知のアカウント/未知の値はサイレントに除外される可能性があり、項目ごとのエラーは保証されません。無料プランのワークスペースは外部メールアドレスをサポートせず、400 になる場合があります。担当者が欠落すると未割り当てのエスカレーションフローに入る可能性があります。 |
| content.config.extend.manager[] | string | 有効な主体、メールアドレス、または dutyPerson を 1 つ指定します。文字列以外は文字列 startswith の処理時に 500 になる可能性があります。 |
| content.config.extend.conditionsInputFilters | any | オプションの任意 JSON で、履歴 Issue/通知イベントからのジャンプ時に補足フィルタを表示するためのものです。実際のクエリは引き続きトップレベルの conditions を使用するため、このキーだけを変更して代用することはできません。 |
| content.config.extend.variable | json | リクエストで入力することは推奨しません。タスクが実際のクエリ列でこのオブジェクトを上書きします。通常 count はウィンドウ内の件数です。 |
| content.config.extend.variable.count | integer | 実行時の出現回数です。呼び出し元の入力は信頼できる固定値として有効になりません。 |
| content.config.extend.tags | json | リクエストで入力することは推奨しません。タスクが実際のグループタグで上書きし、Issue の重複排除およびテンプレート変数に使用されます。 |
| content.config.extend.tags.フィールド | any | 動的な JSON タグ値です。呼び出し元が手入力した値によってグループ生成を固定することはできません。 |
| content.config.extend.channelUUIDs | array | 実行時に有効な設定チャンネルで上書きされます。この拡張フィールドを config.channelUUIDs の代用にしないでください。 |
| content.config.extend.channelUUIDs[] | string | 実行時に有効なチャンネル識別子を 1 つ指定します。 |
| content.config.extend.カスタムキー | any | 任意の JSON 保存値です。本ページで公開されている追加の実行保証はありません。認証情報を入れないでください。 |
| content.config.extend | object または null | 保存済みの拡張です。新しいリクエストではオブジェクトを使用してください。null は同期監査や後続タスクの異常を引き起こします。 |
| content.declaration | object または null | 現在のワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "iatdc_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": null,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"name": "生产事件自动发现",
"description": "按服务聚合生产告警",
"dqlNamespace": "keyevent",
"every": 300,
"conditions": "`df_status` = 'error'",
"dimensions": [
"service"
],
"config": {
"name": "服务{{service}}告警",
"description": "本窗口{{count}}条事件",
"channelUUIDs": [],
"extend": {
"text": "服务{{service}}发现{{count}}条事件",
"manager": []
}
},
"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 ファイルの形式エラー | パラメータオブジェクトを送信してください。 |
| 400 | ft.IssueAutoDiscoveryCfgNameExists | 現在のワークスペースで削除されていないルール名が重複 | 同じ名前のルールが既に存在します | 未使用の名前を選択し、失敗/タイムアウト時はまず既存の設定を確認してください。 |
| 406 | ft.IssueLevelNotExists | config.level が空でなく、現在有効な Issue レベルに存在しない | レベル設定が存在しません | Issue レベル一覧で uuid を確認してください。表示名/インシデントセンターのレベルを混用しないでください。 |
| 404 | ft.NotFoundChannel | ワークスペースに有効なチャンネルがない、または指定した channelUUIDs の項目が有効なチャンネルにない | 指定されたチャンネルが見つかりません | ワークスペースに有効なチャンネルがあることを確認し、チャンネル簡易一覧から UUID を選択してください。[] でも「ワークスペースに少なくとも 1 チャンネル」の要件は回避できません。 |
| 400 | ft.UnsupportFreeIssueManager | 無料プランのワークスペースで担当者に非メンバーの外部メールアドレスを使用 | 無料プランのワークスペースでは、インシデントの担当者に外部メールアドレスを使用できません | 本ワークスペースのメンバーを使用するか、管理者に製品プランを確認してください。 |
| 500 | ft.InternalServerError | テンプレート/担当者/ディメンションの同期監査資料の構築、設定のデータベース書き込み、コンテキストのコミットなどで未処理の例外 | 内部エラー | まず名前で設定を読み取り、保存済みかどうかを確認してください。サブ構造/非文字列のディメンションは通常保存前に失敗します。結果が不明な場合は重複作成せず、traceId を保持して確認してください。 |