変更¶
POST /api/v1/incidents/{incident_uuid}/modify
概要¶
インシデントのフィールド、担当者、ステータス、タグの関連付けを変更します。
呼び出し前の準備と使用手順¶
現在のルートは実際に anomaly.issueManage を要求します。incidents.incidentsManage のみを設定して書き込み可能と仮定することはできません。操作できるのは現在の API Key が属するワークスペースのみです。本モジュールのインシデント UUID はインシデント一覧の content.data[].uuid から取得し、通常は incident_ プレフィックスが付きます。公開エンドポイントは workspaceUUID/workspaceUUIDs を受け付けないため、フロントエンド/内部インターフェースのクロスワークスペースパラメータをそのまま流用しないでください。
省略したフィールドは保持されます。name/description/level/assigner/incidentsStatus/extend/添付ファイル/タグは、それぞれのパラメータごとに処理されます。resourceURL と dimensionTag はルートで宣言されていますが、現在のコントローラーでは更新されません。HTTP 200 を受けてこれらのフィールドが変更されたと判断しないでください。extend は patch ではなく全体置換です。添付ファイルリストは追加/再バインドであり、[] を渡してもバインド解除されません。{} を渡しても更新時刻は更新され、非同期の更新通知が発行される可能性があります。
assigner を渡すと、ステータスが open で元の担当者が空の場合は working へ遷移します。[] を渡した場合も同様です。また、明示的に incidentsStatus=open を渡すと最終的に担当者がクリアされます。インシデントを再オープンするとタイマーがリセットされ、現在のサイクルのイベント関連付けが初期化されますが、以前の担当者が自動的に復元されることはありません。ステータス、レベル、担当者の変更は操作履歴として記録され、Webhook/通知が送信されます。一部のキュー更新は本体のコミットより前に発生する可能性があります。
インシデント、添付ファイル、タグ、操作履歴、および非同期ディスパッチは単一のトランザクションではありません。添付ファイルのバインド自体もコミットされます。500/タイムアウトの場合でも本体や一部の添付ファイル/タグが保存されている可能性があり、作成時には通知がキューに登録されている可能性もあります。まず詳細/一覧を読み戻して確認してから、再試行するかどうかを判断してください。作成には冪等キーや名前の重複排除がないため、リクエストを繰り返すと重複したインシデントが作成される可能性があります。HTTP の成功はインターフェースの処理が完了したことのみを示し、Webhook/Agent/オンコール通知が実際に実行または配信されたことを保証するものではありません。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| incident_uuid | string | Y | 現在のワークスペースのインシデント UUID です。アラートイベント ID、SLO UUID、コメント UUID ではありません。 null 許可: False 例: incident_example取得/入力方法: インシデント一覧から content.data[].uuid を取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報です。 例: <DF-API-KEY>取得/入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
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取得/入力方法: 顧客がアクセス可能なリンク。 |
|
| assigner[*] | string | 担当者のアカウント/グループ/通知先の UUID 文字列です。 例: acnt_example取得/入力方法: メンバー一覧からアカウント UUID を取得します。グループ/通知先はそれぞれ対応する一覧から取得し、同一ワークスペースに属し利用可能であることを確認してください。 |
|
| assigner | array | オプションの配列です。省略時は保持され、指定時は全体置換、[] でクリアされます。現在担当者がなくステータスが open の場合、[] を渡しても自動的に working へ遷移する可能性があります。最後に明示的に incidentsStatus=open を指定すると、再度担当者がクリアされます。現在、未知の識別子を項目ごとに拒否することはなく、レスポンスの assignerInfo には解析に成功した項目のみが含まれます。 null 許可: False 例: ["acnt_example"]取得/入力方法: メンバー一覧からアカウント UUID を取得します。グループ/通知先はそれぞれ対応する一覧から取得し、同一ワークスペースに属し利用可能であることを確認してください。 |
|
| 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 全体をコピーしてください。 |
|
| incidentsStatus | string | オプションで open/working/resolved/closed を指定します。省略時は保持されます。open は担当者をクリアし、再オープンは新しいライフサイクルを開始して関連イベントのスナップショットをクリアします。resolved/closed は通知キューを更新しますが、インシデントは削除しません。 null 許可: False 選択可能な値: ['open', 'working', 'resolved', 'closed'] 例: working取得/入力方法: 業務ライフサイクルに応じて選択し、事前に現在の状態を読み戻してください。 |
|
| level | string | 作成時は必須、変更時は省略可能です。P1 名ではなくレベル UUID を使用します。現在、作成/変更時にレベルの有効性を強制検証しないため、一覧に無効化済みのデフォルト項目が含まれる場合があります。保存に成功したからといってレベルが利用可能であるとは判断できません。 null 許可: False 例: system_level_1取得/入力方法: インシデントレベル一覧から uuid を取得します。バックエンドでグローバルレベルが有効な場合は、管理者に実際に有効なレベルを確認してください。 |
|
| name | string | 作成時は必須、変更時はオプションです。最大 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 を含む名前を選択します。新しいタグ名を作成することもできます。 |
パラメータ補足説明¶
パラメータを省略した場合は保持されます。resourceURL/dimensionTag は現在更新されず、extend は全体置換です。添付ファイル UUID リストではクリア/バインド解除は実行されません。変更権限は現在の anomaly.issueManage の宣言に従います。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/incidents/incident_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"assigner":["acnt_example"],"incidentsStatus":"working"}'
レスポンス¶
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 Key の場合は通常 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 | インシデントのソースです。本公開エンドポイントで手動作成した場合は現在 external となり、External API 認証を使用したことを意味するものではありません。 |
| content.resourceCategory | string | ソースリソースのカテゴリです。自動生成のインシデントではソースに応じて設定され、公開エンドポイントからの手動作成では通常空です。 |
| content.resourceType | string | ソースリソースのタイプです。集約インシデントの場合は incident_aggregation、手動作成では通常空です。 |
| content.resourceUUID | string | ソースリソースの UUID です。手動作成では通常空です。 |
| content.resourceUrl | string | 保存されたソース URL です。レスポンスのフィールドは先頭の l が小文字で、リクエストの 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 | 保存された担当者/グループ/通知先の識別子 1 つです。 |
| 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.assignerInfo | array<object> |
実際に解析に成功した担当者のサマリーです。アカウントは完全な身元フィールドを持ち、グループ/通知先は uuid/name のみを含みます。未知の識別子は無視される場合があります。 |
| content.assignerInfo[].uuid | string | 主体の UUID です。システムが返す主体の場合は空またはシステム識別子になることがあります。 |
| content.assignerInfo[].status | integer | 主体のステータスです。 |
| content.assignerInfo[].wsAccountStatus | integer | ワークスペースメンバーのステータスです。Key の場合は Key のステータスとなり、インシデントのステータスではありません。 |
| content.assignerInfo[].username | string | ログイン名/Key 名/システム名です。 |
| content.assignerInfo[].name | string | 表示名です。システム AI の表示名はサイト設定を使用します。 |
| content.assignerInfo[].iconUrl | string | アバター URL です。システムサマリーでは省略される場合があります。 |
| content.assignerInfo[].email | string | 連絡先メールアドレスです。Key のサマリーでは Key UUID となる場合があり、配信可能なメールアドレスではありません。 |
| content.assignerInfo[].mobile | string | 連絡先携帯電話番号です。空になることがあります。 |
| content.assignerInfo[].countryCode | string | 国番号です。システムサマリーでは省略される場合があります。 |
| content.assignerInfo[].acntWsNickname | string | ワークスペースのニックネームです。システムサマリーでは省略される場合があります。 |
| content.attachments | array<object> |
関連付け済み添付ファイルのサマリーです。未関連付けの場合は [] です。 |
| content.attachments[].uuid | string | 添付ファイル UUID です。本モジュールの downloadAttachment インターフェースでダウンロードします。 |
| content.attachments[].fileName | string | 元のファイル名です。 |
| content.attachments[].fileSuffix | string | ファイル拡張子です。ドットは含みません。ファイル内容/直リンクは返されません。 |
| 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": 123,
"uuid": "incident_example",
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"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": [
"acnt_example"
],
"incidentsStatus": "working",
"statusTime": {
"open": 1785427200,
"working": 1785427260
},
"statusChangeTime": 1785427200,
"cumulativeTime": 0,
"eventCount": 0,
"eventUpdateAt": 0,
"dimensionTag": {
"service": "payment"
},
"extend": {},
"dtHost": "",
"dtResource": "",
"dtPodName": "",
"dtAppName": "",
"dtAppId": "",
"dtEnv": "",
"dtUrl": "",
"dtService": "payment",
"assignerInfo": [
{
"uuid": "acnt_example",
"name": "处理人"
}
],
"attachments": [],
"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.IncidentsNotFound | 対象のインシデントが現在のワークスペースに存在しないか、削除済みです | 指定されたインシデントが見つかりません | インシデント一覧から content.data[].uuid を再取得してください。 |
| 400 | ft.TagScopeMismatch | 書き込むタグに同名のものが既に存在しますが、scope に monitor/all が含まれていません | production: ['scene'] -> monitor | monitor スコープまたはグローバルタグを選択してください。 |
| 406 | ft.ExceedMaxCharacterLimit | タグ名が 128 文字を超えています | {} が最大文字長の制限を超えています | タグ名を短くしてください。 |
| 500 | ft.InternalServerError | データベース、キャッシュ/キュー、無効な添付ファイル、展開されていない子フィールドの型/履歴の異常構造、または下流の未処理例外 | 内部エラー | 読み取り専用リクエストはバックオフして再試行できます。書き込みリクエストはまずインシデント/コメントの現状と通知記録を読み取り、既にコミットされている可能性があるため、重複作成や重複通知を避けてください。 |