作成¶
POST /api/v1/incidents/add
概要¶
現在のワークスペースにインシデントを手動で作成し、関連タスクを非同期でディスパッチします。
呼び出し前の準備と使用手順¶
キーには incidents.incidentsManage が必要です。現在の API キーが属するワークスペースのみを操作します。本モジュールのインシデント UUID はインシデント一覧の content.data[].uuid から取得し、通常は incident_ プレフィックスです。公開エンドポイントは workspaceUUID/workspaceUUIDs を受け付けないため、フロントエンド/内部インターフェースのクロスワークスペースパラメータをそのまま流用しないでください。
初期の業務ステータスは open に固定され、公開リクエストは assigner/incidentsStatus/resourceType を受け付けません。作成後は更新インターフェースで担当者/ステータスを指定する必要があります。名前は重複可能です。level は UUID を保存するだけで有効性を検証しないため、事前にレベルを確認してください。現在、extend で送信した内容は保存されません。dimensionTag はオブジェクトを渡す必要があります。
インシデント、添付ファイル、タグ、操作記録、および非同期ディスパッチは単一のトランザクションではありません。添付ファイルのバインド自体はコミットされます。500/タイムアウトでも本体または一部の添付ファイル/タグが保存されている可能性があり、作成では通知がすでにキューに登録されている場合もあります。まず詳細/一覧を再取得して確認してから、再試行するか判断してください。作成には冪等キーや名前の重複排除がないため、重複リクエストで重複したインシデントが作成される可能性があります。HTTP 成功はインターフェースの処理完了を示すだけであり、Webhook/Agent/オンコール通知が実際に実行または配信されたことを証明するものではありません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API キー管理から、この操作権限を持つ OpenAPI キーを取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| tags[*] | string | monitor/all スコープのタグ名。 例: production取得または入力方法: タグ一覧から scope に monitor/all を含む名前を選択します。新しいタグ名を作成することもできます。 |
|
| attachmentUUIDs[*] | string | 検証済みの添付ファイル UUID 文字列。 例: att_example取得または入力方法: まず添付ファイルのアップロードで content.attachmentUuid を取得し、ファイルが今回の操作で使用を許可されている添付ファイルであることを確認します。 |
|
| dimensionTag.カスタムキー | string | 動的ディメンション値。文字列を推奨。作成時はカスタムキーをサポートしますが、更新時は現在有効になりません。 例: payment取得または入力方法: ソースイベント/リソースのディメンションキーと値。 |
|
| extend.linkList | array | リンクオブジェクトの配列。作成時は extend を無視し、更新時のみ保存します。 例: [{"name": "排查手册", "link": "https://example.com/runbook"}]取得または入力方法: 呼び出し元に関連する業務リンク。 |
|
| extend.linkList[*].name | string | リンク表示名の文字列。 例: 排查手册取得または入力方法: 業務リンクの表示名。 |
|
| extend.linkList[*].link | string | リンク URL 文字列。本インターフェースは到達可能性を検証しません。 例: https://example.com/runbook取得または入力方法: 顧客がアクセス可能なリンク。 |
|
| attachmentUUIDs | array | 配列の各項目は添付ファイル UUID であり、URL ではありません。省略するとバインドされません。指定された場合は 1 件ずつ追加/再バインドされます。[] は既存の添付ファイルをクリアせず、全量置換でもありません。無効/削除済みの添付ファイルは 500 になる可能性があります。このバインドチェーンはソースワークスペース/元の関連付けを確実には検証しないため、呼び出し元は自分で確認済みの添付ファイルのみを使用し、他のリソースの添付ファイルを借用しようとしないでください。 null 許可: False 例: ["att_example"]取得または入力方法: まず添付ファイルのアップロードで content.attachmentUuid を取得し、ファイルが今回の操作で使用を許可されている添付ファイルであることを確認します。 |
|
| description | string | 省略可能な文字列または null。作成時に省略すると空文字列、更新時に省略すると保持、空文字列はクリア、明示的な null は null として保存されます。 null 許可: True 例: 部分请求失败取得または入力方法: インシデントの現象と調査の手がかりを記入します。 |
|
| dimensionTag | json | 作成時は JSON オブジェクトである必要があり、デフォルトは {} です。host/service/resource/pod_name/app_name/app_id/env/url は対応するインデックス列にも同時に書き込まれます。その他のキーは保存できます。ルートパラメータが null/配列/文字列の場合は、まず 406 で拒否されます。ディメンション値は文字列を推奨します。展開されていない子値の型エラーにより、引き続きデータベースエラーが発生する可能性があります。更新時、現在のコントローラはこのパラメータを処理しないため、送信してもディメンションやインデックス列は更新されません。 null 許可: False 例: {"service": "payment"}取得または入力方法: イベントのディメンション情報を入力します。ソースサービス/リソースデータから同じフィールド値を読み取ることを優先してください。 |
|
| extend | json | JSON オブジェクトである必要があります。ルートパラメータが null/配列/文字列の場合は、まず 406 で拒否されます。作成時は現在読み取られますがエンティティには渡されず、送信内容は保存されません。レスポンスは通常 {} です。更新時に指定された場合は全体を置換し、{} はクリア、省略時は保持され、再帰的マージは行いません。内部の未宣言の子フィールドも、後続の読み取りに影響しないよう有効な構造を維持する必要があります。 null 許可: False 例: {"linkList": [{"name": "排查手册", "link": "https://example.com/runbook"}]}取得または入力方法: 呼び出し元が保存すべき業務拡張を入力します。更新前に詳細の extend 全体をコピーしてください。 |
|
| level | string | Y | 作成時は必須、更新時は省略可能。P1 名ではなくレベル UUID を使用します。現在の作成/更新ではレベルの有効性を強制検証しないため、一覧に無効化済みのデフォルト項目が含まれる場合があります。保存成功をもってレベルが利用可能と証明することはできません。 null 許可: False 例: system_level_1取得または入力方法: インシデントレベル一覧から uuid を取得します。バックエンドでグローバルレベルが有効になっている場合は、管理者に実際に有効なレベルを確認する必要があります。 |
| name | string | Y | 作成時は必須、更新時は任意。最大 256 文字と宣言されていますが、データベース列は 128 であるため、1~128 文字の使用を推奨します。現在、非空は強制されていません。更新時に省略すると保持され、空文字列はクリアする可能性があります。 null 許可: False 最大長: 256 例: 支付服务异常取得または入力方法: 呼び出し元が識別可能なインシデントタイトルを提供します。 |
| resourceURL | string | 作成時は任意。省略すると空文字列。サーバーはこのアドレスに自動アクセスしません。レスポンスフィールドは resourceUrl です。更新ルートはこのパラメータを公開していますが、現在のコントローラは値を設定しないため、送信しても既存の URL は変更されません。 null 許可: False 例: https://example.com/runbook取得または入力方法: 顧客がアクセス可能なソースページまたは調査手順書の URL を記入します。 |
|
| tags | array | 書き込みには名前の配列を使用します。1 つの名前は最大 128 文字で、大文字小文字を区別します。作成時に省略するとタグなし、更新時に省略すると保持、[] は関連付けをクリア、指定した場合は全量置換となります。新しいタグは monitor スコープとなり、同名で scope が一致しない既存タグがある場合は 400 になります。 null 許可: False 例: ["production"]取得または入力方法: タグ一覧から scope に monitor/all を含む名前を選択します。新しいタグ名を作成することもできます。 |
パラメータ補足¶
レベル UUID はインシデントレベル一覧から取得し、有効かどうかを確認してください。作成時は担当者とステータスを受け付けません。現在 extend はデータベースに保存されないため、業務リンクは作成成功後に更新インターフェースで全体を保存できます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/incidents/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"支付服务异常","level":"system_level_1","description":"部分请求失败","resourceURL":"https://example.com/runbook","dimensionTag":{"service":"payment"},"tags":["production"]}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | データベース行 ID。業務上の特定には uuid を使用します。送信前のスナップショットでは null になる場合があります。 |
| content.uuid | string | このリソースの UUID。 |
| content.status | integer | データベースステータス。0 はアクティブ、3 は削除。インシデントの業務ステータス incidentsStatus とは異なります。 |
| content.creator | string | 作成主体。API キーの場合は通常 wsak_ リソース UUID です。 |
| content.updator | string | 最終更新主体。未更新の場合は空になることがあります。 |
| content.createAt | integer | Unix 秒の作成時刻。 |
| content.updateAt | integer | Unix 秒の最終更新時刻。 |
| content.deleteAt | integer | Unix 秒の削除時刻。未削除の場合は -1。 |
| content.workspaceUUID | string | インシデントが属するワークスペース。 |
| content.name | string | インシデント名。 |
| content.level | string | インシデントレベル UUID。system_level_0 など、または issl_/isslm_ の履歴識別子。レベルの表示名とは異なります。 |
| content.description | string または null | インシデントの説明。 |
| content.source | string | インシデントのソース。この公開 API による手動作成では現在 external となり、External API 認証を使用していることを示すものではありません。 |
| content.resourceCategory | string | ソースリソースカテゴリ。自動インシデントではソースに応じて設定され、公開エンドポイントからの手動作成では通常空です。 |
| content.resourceType | string | ソースリソースタイプ。集約インシデントでは incident_aggregation、手動作成では通常空です。 |
| content.resourceUUID | string | ソースリソース UUID。手動作成では通常空です。 |
| content.resourceUrl | string | 保存されたソース URL。レスポンスフィールドは resourceUrl で、リクエストの resourceURL とは異なります。 |
| content.resourceContent | object または JSON | ソースの元の内容。型はモニター/イベント/集約ソースによって変化します。一覧ではこのフィールドは削除されます。 |
| content.eventRelations | array<object> |
現在のインシデントライフサイクルに関連するイベントのスナップショット。再度開いて新しいサイクルになるとクリアされる場合があります。 |
| content.eventRelations[] | object | ソースイベントの関連付け記述。イベントタイプに応じて動的フィールドを返します。本インターフェースでインシデントを作成する際に設定できるオブジェクトではありません。 |
| content.eventRelations[].カスタムフィールド | JSON | イベント生成側が保存した関連キーと値。実際の型に従って読み取ってください。 |
| content.resourceIdentity | string | ソースの集約/子識別子。手動作成では空になる場合があります。 |
| content.assigner | array<string> |
担当者識別子のリスト。acnt_/group_/notify_ を含む場合があります。すべての識別子がまだ有効であることは保証されません。 |
| content.assigner[] | string | 保存された担当者/グループ/通知先の識別子。 |
| content.incidentsStatus | string | 業務ステータス open/working/resolved/closed。 |
| content.statusTime | object | 現在のライフサイクルで記録済みのステータス時刻(Unix 秒)。すべてのステータスが存在するわけではありません。 |
| content.statusTime.open | integer | 今回のサイクルで開いた時刻。 |
| content.statusTime.working | integer | 今回のサイクルで処理中になった時刻。省略される場合があります。 |
| content.statusTime.resolved | integer | 今回のサイクルで復旧した時刻。省略される場合があります。 |
| content.statusTime.closed | integer | 今回のサイクルでクローズした時刻。省略される場合があります。 |
| content.statusChangeTime | integer | 現在のライフサイクルのトリガー時刻。再オープン時に更新されます。フィールドを変更するたびの時刻とは異なります。 |
| content.cumulativeTime | integer | インシデントの累計継続秒数。詳細/一覧では現在のステータスを組み合わせてリアルタイム計算され、書き込みレスポンスでは保存値となる場合があります。 |
| content.eventCount | integer | 関連イベント数。手動作成では通常 0 です。 |
| content.eventUpdateAt | integer | ソースの最新イベント更新時刻(Unix 秒)。手動作成では通常 0 です。 |
| content.dimensionTag | object | ディメンション名から値への JSON マッピング。 |
| content.dimensionTag.カスタムキー | JSON | 呼び出し元またはソースが保存したディメンション値。文字列を推奨。host/service などには別途インデックスフィールドがあります。 |
| content.extend | object または JSON | インシデントの拡張データ。自動ソースでは集約/イベントなどの設定が付随する場合があります。公開エンドポイントからの作成では現在、送信された extend を保存せず、更新時のみ全体を置換できます。 |
| content.extend.linkList | array<object> |
業務リンクの配列。保存後は表示用途であり、本インターフェースが外部 URL にアクセスするものではありません。 |
| content.extend.linkList[].name | string | リンク表示名。 |
| content.extend.linkList[].link | string | リンクアドレス。 |
| content.extend.aggregationRuleUUID | string | 集約ソースルール UUID。存在する場合、filters.aggregationRuleUUID に使用できます。 |
| content.extend.カスタムフィールド | JSON | その他保存されたソース拡張フィールド。固定構造は保証されません。全体を置換する前に既存オブジェクト全体をコピーしてください。 |
| content.dtHost | string または null | host インデックスディメンション。作成時の dimensionTag に由来します。公開エンドポイントからの更新では dimensionTag は現在有効になりません。 |
| content.dtService | string または null | service インデックスディメンション。作成時の dimensionTag に由来します。公開エンドポイントからの更新では dimensionTag は現在有効になりません。 |
| content.dtResource | string または null | resource インデックスディメンション。作成時の dimensionTag に由来します。公開エンドポイントからの更新では dimensionTag は現在有効になりません。 |
| content.dtPodName | string または null | pod_name インデックスディメンション。作成時の dimensionTag に由来します。公開エンドポイントからの更新では dimensionTag は現在有効になりません。 |
| content.dtAppName | string または null | app_name インデックスディメンション。作成時の dimensionTag に由来します。公開エンドポイントからの更新では dimensionTag は現在有効になりません。 |
| content.dtAppId | string または null | app_id インデックスディメンション。作成時の dimensionTag に由来します。公開エンドポイントからの更新では dimensionTag は現在有効になりません。 |
| content.dtEnv | string または null | env インデックスディメンション。作成時の dimensionTag に由来します。公開エンドポイントからの更新では dimensionTag は現在有効になりません。 |
| content.dtUrl | string または null | url インデックスディメンション。作成時の dimensionTag に由来します。公開エンドポイントからの更新では dimensionTag は現在有効になりません。 |
| content.eventRelations[].df_fault_id | string | イベントライフサイクル ID。イベントの df_fault_id または互換の df_status_fault_id から生成されます。インシデント uuid ではありません。 |
| content.eventRelations[].status | string | この関連イベントスナップショットの df_status ステータス(例: critical/ok)。インシデントの incidentsStatus とは異なります。 |
| content.eventRelations[].aggregationValues | object | 集約ルールによる関連付けの場合のみ存在可能。集約キーから対応するイベントのディメンション値へのマッピング。 |
| content.eventRelations[].aggregationValues.集約キー | JSON | 集約ルールで指定されたディメンションのイベント内での値。実際に保存された型に従って読み取ってください。 |
| content.tagInfo | array<object> |
今回送信されたタグを解析した後のサマリー。このフィールドを実際に組み立てるレスポンス分岐でのみ出現します。 |
| content.tagInfo[].id | string | 互換タグ ID。uuid と同じです。 |
| content.tagInfo[].uuid | string | タグ UUID。一覧の tags フィルタに使用し、書き込み時は name を使用します。 |
| content.tagInfo[].name | string | タグ名。 |
| content.tagInfo[].scope | array<string> |
有効なスコープ。現在の新規作成では monitor、履歴のグローバルでは all になる場合があります。 |
| content.tagInfo[].scope[] | string | all/scene/monitor/dialing/security/infrastructure/catalog のいずれか。 |
| content.declaration | object | 現在のワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "incident_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"workspaceUUID": "wksp_example",
"name": "支付服务异常",
"level": "system_level_1",
"description": "部分请求失败",
"source": "external",
"resourceCategory": "",
"resourceType": "",
"resourceUUID": "",
"resourceUrl": "https://example.com/runbook",
"resourceContent": {},
"eventRelations": [],
"resourceIdentity": "",
"assigner": [],
"incidentsStatus": "open",
"statusTime": {
"open": 1785427200
},
"statusChangeTime": 1785427200,
"cumulativeTime": 0,
"eventCount": 0,
"eventUpdateAt": 0,
"dimensionTag": {
"service": "payment"
},
"extend": {},
"dtHost": "",
"dtResource": "",
"dtPodName": "",
"dtAppName": "",
"dtAppId": "",
"dtEnv": "",
"dtUrl": "",
"dtService": "payment",
"tagInfo": [
{
"id": "tag_example",
"uuid": "tag_example",
"name": "production",
"scope": [
"monitor"
]
}
],
"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.TagScopeMismatch | 書き込みタグに同名が存在するが scope に monitor/all が含まれていない | production: ['scene'] -> monitor | monitor スコープまたはグローバルタグを選択してください。 |
| 406 | ft.ExceedMaxCharacterLimit | タグ名が 128 文字を超えている | {} が最大文字長制限を超えています | タグ名を短くしてください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ/キュー、無効な添付ファイル、展開されていない子フィールドの型/履歴の異常構造、または下流の未処理例外 | 内部エラー | 読み取り専用リクエストはバックオフして再試行できます。書き込みリクエストは、まずインシデント/コメントの現在の状態および通知記録を読み取ってください。すでにコミットされている可能性があるため、重複作成や重複通知を避けてください。 |