コンテンツにスキップ

作成



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 データベース、キャッシュ/キュー、無効な添付ファイル、展開されていない子フィールドの型/履歴の異常構造、または下流の未処理例外 内部エラー 読み取り専用リクエストはバックオフして再試行できます。書き込みリクエストは、まずインシデント/コメントの現在の状態および通知記録を読み取ってください。すでにコミットされている可能性があるため、重複作成や重複通知を避けてください。

フィードバック

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