未復旧イベントの一覧表示¶
POST /api/v1/events/abnormal/list
概要¶
現在のワークスペースで未復旧のモニタリングイベントまたはカスタムイベントを一覧表示し、イベント関連識別子ごとにグループ化して最新のステータスを返します。
呼び出し前と使用手順¶
同じ df_monitor_checker_event_ref でグループ化し、最新のステータスが fatal、critical、error、warning、nodata のいずれかであるイベントを返します。統合収集イベントと大規模イベントの集計はこのリストに含まれません。現在の公開リクエストでは引き続き timeRange に 2 つのミリ秒整数を指定する必要がありますが、このバージョンではこのフィールドはクエリウィンドウの設定には使用されず、実際にはサーバー側の現在時刻から過去 48 時間が使用されます。任意の履歴期間の結果を推測するために使用しないでください。履歴範囲を指定するには、DQL クエリを使用できます。search はタイトルと説明を検索し、lastStatus は最終ステータスをさらに限定します。デフォルトは offset=0、limit=20 です。以降は空の data が返るか total_count に達するまで、offset に limit を加算します。クエリ中にイベントは変化するため、ページ間のデータおよび件数が変化する可能性があります。この API は現在の API Key が属するワークスペースを使用し、クロスワークスペースまたはクロスサイトのパラメータは宣言されていません。他のワークスペースまたはサイトでは、対応するサイトの Endpoint と、対応するワークスペースの API Key を使用して個別に呼び出してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエスト Body パラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| filters[*] | json | 単一の条件オブジェクト。通常の条件では name、operation、value を入力し、ネストしたグループでは filters を入力します。condition を別途設定できます。 例: {"name": "df_source", "operation": "=", "value": ["monitor"], "condition": "and"}取得または入力方法: 各項目をフィールド条件またはネストした条件グループとして入力します。 |
|
| filters[*].name | string | フィールド名。通常の条件では必須です。 例: df_source取得または入力方法: イベント詳細で返される元のフィールド名(例: df_source、df_monitor_checker_name、収集ディメンション)を使用します。 |
|
| filters[*].operation | string | 通常の条件では必須です。使用可能な値: =、!=、>、>=、<、<=、in、not in(notin と互換)、wildcard、not wildcard、query_string、exists、not_exists、match、not match(notmatch と互換)、re、=~、!=~。between はサポートされません。範囲には >= と <= の 2 つの条件を使用します。例: =取得または入力方法: フィールドとクエリの目的に応じて、以下の演算子から選択します。ネストした filters グループでは省略します。 |
|
| filters[*].value | array | 比較値の配列。in/not in はすべての値を使用し、その他の値を持つ演算は通常最初の項目を使用します。exists/not_exists では [] を渡せます。 例: ["monitor"]取得または入力方法: そのフィールドに実際に存在する値を使用し、文字列、数値、ブール値は元のデータ型と一致させます。 |
|
| filters[*].value[*] | string/number/boolean | 単一の文字列、数値、またはブール値。配列全体を文字列に再シリアライズしないでください。 例: monitor取得または入力方法: 対象イベントの同じフィールドから値を取得するか、比較する数値しきい値を入力します。 |
|
| filters[*].condition | string | 論理連結。省略時はデフォルトで AND です。各グループの最初の条件の連結子は有効になりません。 例: and取得または入力方法: 前の条件との関係に応じて and または or を選択します。 |
|
| filters[*].filters | array | 子条件グループ。このフィールドが存在する場合、この項目の name、operation、value は条件の構築に使用されません。再帰的にネストできます。 例: [{"name": "df_monitor_checker_name", "operation": "wildcard", "value": ["*checkout*"]}]取得または入力方法: 括弧による組み合わせが必要な場合、filters と同じ構造の子配列を入力します。 |
|
| filters | array | イベントフィルター条件の配列。複数の条件はデフォルトで AND となり、子条件を再帰的に構成できます。 null を許可: False 例: [{"name": "df_source", "operation": "=", "value": ["monitor"], "condition": "and"}]取得または入力方法: まずイベント詳細またはイベントフィールドリファレンスで元のフィールド名を確認し、以下のフィルター構造に従って入力します。省略または [] の場合はカスタムフィルターを追加しません。 |
|
| lastStatus | string | 最新イベントの異常ステータス。省略時は上記のすべての未復旧ステータスに一致します。 null を許可: False 選択可能な値: ['fatal', 'critical', 'error', 'warning', 'nodata'] 例: critical取得または入力方法: fatal、critical、error、warning、nodata から 1 つ選択します。 |
|
| limit | integer | 返却件数の上限。デフォルトは 20 です。 null を許可: False $maxValue: 100 $minValue: 1 例: 20取得または入力方法: 読み取り要件に応じて 1 から 100 の整数を選択します。 |
|
| offset | integer | 結果のオフセット。非負整数で、デフォルトは 0 です。 null を許可: False $minValue: 0 例: 0取得または入力方法: 最初のページは 0 を入力し、以降は今回の limit を加算します。フィルター条件は変更しないでください。 |
|
| search | string | タイトルと説明を検索します。省略時はデフォルトで空文字列となり、キーワードフィルターを追加しません。 null を許可: False 例: checkout取得または入力方法: イベントのタイトルまたは説明に含まれるキーワードを入力します。 |
|
| timeRange | array | Y | 互換性のための時間範囲フィールド。長さは 2 である必要があります。現在の API ではこの値でクエリを限定しません。 null を許可: False 最大長: 2 最小長: 2 例: [1785427200000, 1785430800000]取得または入力方法: クライアントの時間セレクターに従って開始と終了の Unix ミリ秒を生成し、配列として渡します。このバージョンではフィールドは引き続き必須ですが、実際のウィンドウについては説明を参照してください。 |
| timeRange[*] | integer | Y | 配列内の Unix ミリ秒タイムスタンプ。 null を許可: False 例: 1785427200000取得または入力方法: JavaScript の Date.getTime() などを使用し、ミリ秒の整数を指定します。 |
パラメータの補足説明¶
イベントフィールドと収集の意味については、イベントフィールドリファレンスを参照してください。filters では operation の代わりに op、value の代わりに values、condition の代わりに logic を互換的に使用できますが、表中の完全な名前を統一して使用することを推奨します。ネストしたフィールドには項目ごとの構造検証がなく、operation の欠落や誤った型は一般的な内部エラーを引き起こす可能性があるため、送信前に例に従って検証してください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/events/abnormal/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"timeRange":[1785427200000,1785430800000],"lastStatus":"critical","filters":[{"name":"df_source","operation":"=","value":["monitor"],"condition":"and"}],"offset":0,"limit":20}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要なフィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 未復旧イベントとページングオフセット情報。 |
| content.data | array<object> |
現在のページの未復旧イベント。結果がない場合は [] です。 |
| content.data[].__docid | string | イベントドキュメント ID。イベント詳細のパス doc_id に入力します。df_event_id やイベント関連識別子とは異なります。 |
| content.data[].time | integer | イベントクエリで返される時刻。Unix ミリ秒。 |
| content.data[].date | integer | 互換性のための時間フィールド。リストでは time と同じで、Unix ミリ秒です。 |
| content.data[].df_title | string | イベントタイトル。 |
| content.data[].df_message | string | イベントの詳細説明。 |
| content.data[].df_status | string | イベントステータス。未復旧リストでは fatal、critical、error、warning、nodata です。詳細では ok、info、またはその他のソースで定義された復旧ステータスとなる場合があります。 |
| content.data[].df_source | string | イベントソース。monitor はモニタリングイベント、custom はこのモジュールで作成されたカスタムイベントです。 |
| content.data[].df_event_id | string | イベントの一意の ID。詳細パスの doc_id には使用しません。 |
| content.data[].df_monitor_checker_event_ref | string | 同じトリガー対象のイベント関連識別子。グループ化と復旧に使用され、単一イベントの ID としては使用できません。 |
| content.data[].df_dimension_tags | string または null | 検出ディメンションタグ。多くの場合 JSON オブジェクトをシリアライズした文字列です。値がある場合は解析して service、host などの実際のディメンションを読み取れます。 |
| content.data[].df_check_range_start | integer | 検出範囲の開始時刻。Unix 秒。リストで欠落している場合は 0 で補完されます。 |
| content.data[].df_check_range_end | integer | 検出範囲の終了時刻。Unix 秒。リストで欠落している場合は 0 で補完されます。 |
| content.data[].df_fault_start_time | integer または null | 今回のインシデント開始時刻。Unix 秒。ソースが提供する場合にのみ返されます。 |
| content.data[].df_fault_id | string または null | 今回のインシデント ID。通常、最初のインシデントイベントの df_event_id です。 |
| content.data[].df_monitor_checker | string または null | 検出関数名。例: custom_metric。 |
| content.data[].df_monitor_checker_name | string または null | モニター名。 |
| content.data[].df_monitor_checker_value | number、string または null | イベント発生時の検出値。単位はモニターのメトリクス設定によって決まり、一律にミリ秒として扱うことはできません。 |
| content.data[].df_monitor_type | string または null | モニタリングタイプ。例: custom、slo、bot_obs。統合収集 integration_collection はこの未復旧リストの対象外です。 |
| content.data[].df_workspace_uuid | string または null | イベントレコード内のワークスペース識別子。 |
| content.data[].df_meta | string、object または null | ソースが提供する拡張メタデータ。文字列の場合は JSON シリアライズ値です。構造はイベントソースによって異なります。 |
| content.data[].df_bot_obs_detail | string、object または null | インテリジェントインスペクションイベントの追加詳細。このソースでない場合は欠落する可能性があります。 |
| content.data[].df_event_detail | string、object または null | イベントソースが提供する拡張詳細。フィールドは対応するモニタリングタイプに応じて提供されます。 |
| content.data[].df_is_silent | boolean、number または null | ソースに記録されたミュートフラグ。リストではこの元の値を一律に boolean に変換しません。 |
| content.data[].df_sent_target_types | array、string または null | ソースに記録された通知先タイプ。ソースおよび履歴レコードの形式によって変化する可能性があります。 |
| content.data[].df_alert_info | string、object または null | ソースに記録されたアラート情報。構造はイベントタイプによって変化します。 |
| content.data[].isRecover | boolean | 一部のクエリパスで返される復旧中フラグ。省略されることがあります。存在する場合は復旧処理中としてマーク済みかどうかを示します。true は最終的な復旧成功を意味しないため、引き続きステータスを照会してください。 |
| content.data[].alert_time_ranges | array<array<integer\|null>> |
異常時間帯のリスト。開始時刻の昇順で、各項目は [開始ミリ秒,終了ミリ秒] です。未復旧の場合、終了時刻は null になることがあります。 |
| content.data[].alert_time_ranges[*] | array | 単一の異常区間 [start,end]。 |
| content.data[].alert_time_ranges[*][0] | integer または null | 区間の開始。Unix ミリ秒。 |
| content.data[].alert_time_ranges[*][1] | integer または null | 区間の終了。Unix ミリ秒。終了していない場合は null です。 |
| content.data[].issueLists | array<object> |
関連付けられた Issue のリスト。関連付けがない場合は [] です。 |
| content.data[].issueLists[].issueName | string | 関連付けられた Issue の名前。 |
| content.data[].issueLists[].issueUUID | string | 関連付けられた Issue UUID。 |
| content.data[].incidentsList | array<string> |
イベントに関連付けられたインシデント UUID のリスト。関連付けがない場合は [] です。 |
| content.data[].incidentsList[] | string | 単一のインシデント UUID。 |
| content.data[].mute_rule | array<string> |
一致するミュートルールが存在し、ディメンションタグを解析できる場合に返されるミュートルール UUID の配列。一致しない場合は省略されることがあります。 |
| content.data[].mute_rule[] | string | 単一のミュートルール UUID。 |
| content.total_count | integer | クエリで取得されたグループ数。動的データとバックエンドのクエリ制限により、ページングの一貫性が影響を受ける可能性があります。 |
| content.limit | integer | 今回の件数上限。 |
| content.offset | integer | 今回のオフセット。 |
| content.declaration | object または null | ワークスペースの共通宣言。各イベントに再帰的に挿入されることはありません。 |
{
"code": 200,
"content": {
"data": [
{
"__docid": "DOC-EXAMPLE",
"time": 1785430800000,
"date": 1785430800000,
"df_title": "checkout-api 响应时间超过阈值",
"df_message": "最近 5 分钟平均响应时间超过 500 ms。",
"df_status": "critical",
"df_source": "monitor",
"df_event_id": "event-example",
"df_monitor_checker_event_ref": "checkout-prod-latency",
"df_dimension_tags": "{\"service\":\"checkout-api\",\"env\":\"production\"}",
"df_check_range_start": 1785430500,
"df_check_range_end": 1785430800,
"df_fault_start_time": 1785430500,
"df_fault_id": "event-fault-example",
"df_monitor_checker": "custom_metric",
"df_monitor_checker_name": "checkout-api 平均响应时间",
"df_monitor_checker_value": 800,
"df_monitor_type": "custom",
"df_workspace_uuid": "wksp_example",
"df_is_silent": false,
"df_sent_target_types": [
"dingtalk"
],
"df_meta": "{}",
"df_bot_obs_detail": null,
"df_event_detail": null,
"df_alert_info": null,
"isRecover": false,
"alert_time_ranges": [
[
1785430500000,
null
]
],
"issueLists": [],
"incidentsList": []
}
],
"total_count": 1,
"limit": 20,
"offset": 0,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラー応答¶
認証、レート制限、および共通リクエストエラーの詳細については、共通エラー定義を参照してください。
結果がない場合は data=[] を返し、イベントが存在しないエラーは報告しません。現在の公開パラメータではデフォルトの 48 時間ウィンドウを変更できません。クエリ量が過剰な場合は、より具体的な filters を使用してください。内部のクロスワークスペースパラメータを渡す必要はありません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたは応答の説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反している | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではありません | 一部の json ファイル形式エラー | 単一の JSON オブジェクトを送信し、配列や文字列を渡さないでください。 |
| 406 | ft.InvalidParameter | filters でサポートされていない演算子が使用されています | パラメータ{}が無効です |
演算子リストに従って修正してください。範囲には >= と <= を使用します。 |
| 503 | ft.QueryServiceUnavailable | クエリサービスが一時的に利用できず、実際の上流が 503 を返しています | クエリサービスが一時的に利用できません。しばらくしてから再試行してください | content.retryable=true を確認してバックオフ付きで再試行してください。失敗が続く場合は traceId を提供してください。 |
| 406 | ft.KodoRequestDeadlineExceeded | イベントクエリがバックエンドで許可された実行時間を超えています | データクエリがタイムアウトしました。原因として、データ量の過多、ネットワーク遅延、サーバー負荷の高さが考えられます。次の方法で解決できます: 1. フィルター条件を追加するか時間範囲を縮小してから、再度クエリを実行してください。 2. しばらく待ってから、再度クエリを試行してください。 |
フィルターに一致するイベント数を減らしてから再試行してください。詳細クエリでは timeRange を縮小できます。 |
| 406 | ft.KodoTooManyRows | クエリデータ量がバックエンドの制限を超えています | クエリ対象のデータ量が最大件数制限を超えています。フィルター条件を追加するか時間範囲を縮小してから、再度クエリを実行してください。 | 明確なイベント条件を使用して一致データを減らしてください。1 回のページサイズを小さくしても、集計コストが必ずしも下がるわけではありません。 |
| 429 | ft.KodoServerOverloaded | クエリサービスがビジーまたは過負荷です | 現在のリクエストが頻繁すぎます。しばらくしてから再試行してください。 | バックオフして再試行し、同時に発行するリクエストを減らしてください。 |
| 500 | ft.InternalServerError | クエリ接続の失敗、上流サービスの異常、その他の内部エラー | 内部エラー | しばらくしてから再試行してください。失敗が続く場合は traceId とマスク済みのリクエストを提供してください。 |