コンテンツにスキップ

自動検出設定の変更



POST /api/v1/issue_auto_discovery/{cfg_uuid}/modify

概要

Issue 自動検出設定と 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 を明示的に指定してください。そうしない場合、保存に成功してもタスクがキー欠落や無効なクエリにより失敗する可能性があります。

name/dqlNamespace/every/config は引き続き公開必須です。config は毎回全体が置換され、以前の子キーは自動的に保持されません。トップレベルの description/conditions/dimensions は省略時に保持され、description/conditions を明示的に空にするとクリアできます。dimensions を指定する場合、[] にはできません。conditions の値を変更すると、初回コミット後の別のコミットで、関連する statusType=10 かつ status が 0 の Issue.eventCount が 0 にクリアされます。ディメンション/頻度のみを変更した場合は同じクリア処理は自動実行されず、以前のタイトル/過去の返信も書き戻されません。2 回目/同期監査が失敗しても設定が保存済みである可能性があるため、まず確認してください。

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 の生成/通知の到達を意味しません。

ルートパラメータ

パラメータ名 型 必須 説明
cfg_uuid string Y 現在の Key ワークスペースの未削除ルール。状態 0(有効)または 2(無効)のいずれでも読み取り/変更できます。欠落時は履歴互換の ft.LogIndexCfgNoExists を使用します。メッセージにはログインデックスとありますが、実際にはこのルール UUID を確認してください。
例: iatdc_example
取得または入力方法: Issue 自動検出ルール一覧 から content.data[].uuid(iatdc_)を取得します。Issue UUID や ErrorTrack ルール UUID は使用しないでください。

リクエストヘッダー

パラメータ名 型 必須 説明
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 1 つの有効な主体、メールアドレス、または dutyPerson。文字列以外の場合は文字列 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 リクエストで指定することは推奨しません。タスクが実際のグループ化 tags で上書きし、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 を解析せず、構文/フィールドの有効性は保証されません。非同期タスクの失敗が今回の API エラーになることはありません。エンティティ列は 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/iatdc_example/modify' \
  -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 です。過去のレコードでは他の名前空間が使用されている可能性がありますが、公開 API で書き戻せることを意味しません。
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 1 つの有効な主体、メールアドレス、または dutyPerson。文字列以外の場合は文字列 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 リクエストで指定することは推奨しません。タスクが実際のグループ化 tags で上書きし、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": 7,
    "uuid": "iatdc_example",
    "status": 0,
    "creator": "wsak_example",
    "updator": "wsak_example",
    "createAt": 1785427200,
    "updateAt": 1785427260,
    "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 テンプレート/担当者/ディメンション、設定保存後のイベント数リセット、または同期監査資料の構築で未処理例外が発生 内部エラー 設定および関連 Issue イベント数を読み戻してください。設定は初回コミット済みの可能性があり、後続のエラーでロールバックされる保証はありません。traceId を保持してください。
404 ft.LogIndexCfgNoExists 現在のワークスペースで未削除の自動検出ルールが存在しない/削除済み/別ワークスペース 指定されたログインデックス設定が存在しない このワークスペースの自動検出一覧から iatdc_ UUID を再取得してください。これは履歴流用のエラーメッセージであり、ログインデックスの新規作成に移らないでください。

フィードバック

このページは役に立ちましたか?