変更¶
POST /api/v1/issue/notification_policy/{issue_notification_policy_uuid}/modify
概要¶
通知ポリシーの通知範囲、関連スケジュール、エスカレーション設定を完全に更新します。
呼び出し前の準備と使用手順¶
変更では、完全な対象 name、スケジュールUUID配列、extend を送信する必要があり、スケジュールの関連付けと extend は全体が置き換えられます。notificationScheduleUUIDs を省略するとスケジュールがクリアされ、extend を省略すると通知範囲とルールがクリアされます。パラメータ表の notification_schedule_uuid は歴史的なパス名であり、ここに入力するのはURL上の実際の issue_notification_policy_uuid に対応する同一のポリシーUUIDです。スケジュールUUIDでも、別のQueryパラメータでもありません。ポリシーはコンソールで対象チャンネルに関連付け、有効な通知スケジュールを関連付ける必要があります。実際の受信者は、スケジュールのタイムゾーン、当日の時間帯、有効期間、ローテーション、通知先によって決まります。ポリシーの保存自体ではテスト通知はすぐに送信されません。エスカレーションはサイトの定期ジョブによって確認され、正確なカウントダウンではありません。トリガー設定の作成または更新後に新規作成された Issue のみを確認します。スケジュールにその時点で有効なターゲットがない場合でも1回のトリガーとして記録されることがあり、トリガー回数を配信回数として扱うことはできません。通知先と実際のメッセージも併せて確認してください。ポリシー本体、関連付け、エスカレーショントリガー設定は段階的に保存されます。失敗またはタイムアウト後は、まず詳細を読み取って既存の変更を確認してから、再試行するかどうかを判断してください。現行バージョンでは、既存ポリシーに noManager/processTimeout/openProcessTimeout の時間型ルールを新たに追加し、かつそのタイプにこれまでトリガー設定が存在しなかった場合に限り、トリガー設定の保存が失敗する可能性があります。ポリシー本体は保存済みである可能性があります。既存の同タイプ設定の更新と eventStorm の新規追加はこの条件に該当しません。失敗後は詳細を読み取り、実際のトリガー動作を確認する必要があります。
パスパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| notification_schedule_uuid | string | Y | パス内の通知ポリシーUUID。スケジュールUUIDではなく、Query を追加で渡す必要もありません。 例: inpy_example取得または入力方法: 通知ポリシー一覧からポリシーUUIDを取得します。この名前は歴史的な宣言にすぎず、実際のURLの issue_notification_policy_uuid に対応します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| notificationScheduleUUIDs[*] | string | 単一の通知スケジュールUUID。通知先UUIDで代替することはできません。 例: nsche_example取得または入力方法: 通知スケジュール一覧から単一のスケジュールUUIDをコピーします。通知スケジュール詳細で設定とターゲットを確認できます。 |
|
| extend.notifyTypes[*] | string | 単一のトリガータイプ。openProcessTimeout も issueUpgrade.processTimeout によって有効化され、issueUpgrade.openProcessTimeout を別途渡す必要はありません。 例: issueUpgrade.eventStorm取得または入力方法: トリガー目的に応じて上記のイベントタイプから1つを選択します。イベントタイプ自体は受信者を指定しません。 |
|
| extend.upgradeCfg.noManager | json | Issue 作成時に有効な担当者がおらず、担当者なし候補に入り、ステータスが Open/Working/Pending の場合、Issue 作成時から待機します。既存 Issue は担当者を削除しただけでは候補に再進入することが保証されません。正の整数秒で、60の倍数を入力します。省略または空オブジェクトの場合、このルールは有効になりません。 例: {"duration": 600, "notifyType": "once"}取得または入力方法: extend.notifyTypes に issueUpgrade.noManager を含めた後、業務上の期待に応じて入力します。 |
|
| extend.upgradeCfg.noManager.duration | integer | 有効時は必須の正の整数秒で、60の倍数、最大31622400秒です。省略または0の場合、このルールは作成されません。 例: 600取得または入力方法: 業務上の待機時間を秒に換算します。例えば600は10分です。 |
|
| extend.upgradeCfg.noManager.notifyType | string | 通知方法。once または cycle で、省略時は once です。 例: once取得または入力方法: 1回だけ通知する場合は once、繰り返し確認して送信する必要がある場合は cycle を入力します。 |
|
| extend.upgradeCfg.noManager.cycleDuration | integer | cycle モードで必須の循環間隔(秒)。毎回 duration を加算するわけではなく、実際には定期ジョブとスケジュールの有効性にも影響されます。 例: 600取得または入力方法: cycle モードでは正の整数秒の間隔を選択します。例えば600は10分です。once モードでは省略します。 |
|
| extend.upgradeCfg.noManager.cycleTimes | integer | cycle モードで必須。最大トリガー回数で、初回を含みます。検証範囲は1~30です。実際の記録回数は正常な配信回数と同じではありません。 例: 3取得または入力方法: cycle モードでは1~30の整数を入力します。once モードでは省略します。 |
|
| extend.upgradeCfg.processTimeout | json | Issue が Open/Working の状態で継続して未完了となっている時間。初回は作成時から計時します。Pending/Resolved/Closed から処理状態に再進入した場合、再進入後の状態記録から計時します。省略または空オブジェクトの場合、このルールは有効になりません。 例: {"duration": 1800, "notifyType": "cycle", "cycleDuration": 600, "cycleTimes": 3}取得または入力方法: extend.notifyTypes に issueUpgrade.processTimeout を含めた後、業務上の期待に応じて入力します。 |
|
| extend.upgradeCfg.processTimeout.duration | integer | 有効時は必須の正の整数秒で、60の倍数、最大31622400秒です。省略または0の場合、このルールは作成されません。 例: 1800取得または入力方法: 業務上の待機時間を秒に換算します。例えば600は10分です。 |
|
| extend.upgradeCfg.processTimeout.notifyType | string | 通知方法。once または cycle で、省略時は once です。 例: cycle取得または入力方法: 1回だけ通知する場合は once、繰り返し確認して送信する必要がある場合は cycle を入力します。 |
|
| extend.upgradeCfg.processTimeout.cycleDuration | integer | cycle モードで必須の循環間隔(秒)。毎回 duration を加算するわけではなく、実際には定期ジョブとスケジュールの有効性にも影響されます。 例: 600取得または入力方法: cycle モードでは正の整数秒の間隔を選択します。例えば600は10分です。once モードでは省略します。 |
|
| extend.upgradeCfg.processTimeout.cycleTimes | integer | cycle モードで必須。最大トリガー回数で、初回を含みます。検証範囲は1~30です。実際の記録回数は正常な配信回数と同じではありません。 例: 3取得または入力方法: cycle モードでは1~30の整数を入力します。once モードでは省略します。 |
|
| extend.upgradeCfg.openProcessTimeout | json | Issue が Open のままの場合のみ有効で、最後のステータス変更時刻から計時します。ステータス記録がない場合は作成時刻から計時します。省略または空オブジェクトの場合、このルールは有効になりません。 例: {"duration": 900, "notifyType": "once"}取得または入力方法: extend.notifyTypes に issueUpgrade.processTimeout を含めた後、業務上の期待に応じて入力します。 |
|
| extend.upgradeCfg.openProcessTimeout.duration | integer | 有効時は必須の正の整数秒で、60の倍数、最大31622400秒です。省略または0の場合、このルールは作成されません。 例: 900取得または入力方法: 業務上の待機時間を秒に換算します。例えば600は10分です。 |
|
| extend.upgradeCfg.openProcessTimeout.notifyType | string | 通知方法。once または cycle で、省略時は once です。 例: once取得または入力方法: 1回だけ通知する場合は once、繰り返し確認して送信する必要がある場合は cycle を入力します。 |
|
| extend.upgradeCfg.openProcessTimeout.cycleDuration | integer | cycle モードで必須の循環間隔(秒)。毎回 duration を加算するわけではなく、実際には定期ジョブとスケジュールの有効性にも影響されます。 例: 600取得または入力方法: cycle モードでは正の整数秒の間隔を選択します。例えば600は10分です。once モードでは省略します。 |
|
| extend.upgradeCfg.openProcessTimeout.cycleTimes | integer | cycle モードで必須。最大トリガー回数で、初回を含みます。検証範囲は1~30です。実際の記録回数は正常な配信回数と同じではありません。 例: 3取得または入力方法: cycle モードでは1~30の整数を入力します。once モードでは省略します。 |
|
| extend.upgradeCfg.eventStorm | json | Issue に記録された eventCount が exceedTimes を厳密に超えた後にトリガーされます。Open/Working の状態では限定されず、完了済みの Issue も件数条件を満たす可能性があります。省略または空オブジェクトの場合、このルールは有効になりません。 例: {"exceedTimes": 60, "notifyType": "once"}取得または入力方法: extend.notifyTypes に issueUpgrade.eventStorm を含めた後、業務上の期待に応じて入力します。 |
|
| extend.upgradeCfg.eventStorm.exceedTimes | integer | イベント件数のしきい値であり、時間ではありません。有効時は必須の正の整数で、31622400を超えません。 例: 60取得または入力方法: 許容できる関連イベント件数に基づいて正の整数のしきい値を設定します。例えば60は eventCount が60を超えた場合にのみトリガーされることを意味します。 |
|
| extend.upgradeCfg.eventStorm.notifyType | string | 通知方法。once または cycle で、省略時は once です。 例: once取得または入力方法: 1回だけ通知する場合は once、繰り返し確認して送信する必要がある場合は cycle を入力します。 |
|
| extend.upgradeCfg.eventStorm.cycleDuration | integer | cycle モードで必須の循環間隔(秒)。毎回 duration を加算するわけではなく、実際には定期ジョブとスケジュールの有効性にも影響されます。 例: 600取得または入力方法: cycle モードでは正の整数秒の間隔を選択します。例えば600は10分です。once モードでは省略します。 |
|
| extend.upgradeCfg.eventStorm.cycleTimes | integer | cycle モードで必須。最大トリガー回数で、初回を含みます。検証範囲は1~30です。実際の記録回数は正常な配信回数と同じではありません。 例: 3取得または入力方法: cycle モードでは1~30の整数を入力します。once モードでは省略します。 |
|
| extend | json | 完全な対象通知設定。省略または {} の場合、保存済みの通知範囲とエスカレーションルールをクリアします。 null を許可: False 例: {"notifyTypes": ["issue.add", "issue.modify", "issueReply.add", "issueUpgrade.noManager", "issueUpgrade.processTimeout", "issueUpgrade.eventStorm"], "upgradeCfg": {"noManager": {"duration": 600, "notifyType": "once"}, "processTimeout": {"duration": 1800, "notifyType": "cycle", "cycleDuration": 600, "cycleTimes": 3}, "openProcessTimeout": {"duration": 900, "notifyType": "once"}, "eventStorm": {"exceedTimes": 60, "notifyType": "once"}}}取得または入力方法: 受信したい Issue アクションとエスカレーションルールに応じて入力します。内容がない場合は {} を渡せます。 |
|
| extend.notifyTypes | array | 通知トリガータイプの配列: issue.add=Issue 作成通知、issue.modify=Issue 変更通知、issueReply.add=返信作成通知、issueReply.modify=返信変更通知、issueReply.delete=返信削除通知、issueUpgrade.noManager=担当者なしのエスカレーション通知、issueUpgrade.processTimeout=対応タイムアウトのエスカレーションで processTimeout と openProcessTimeout の2項目を制御、issueUpgrade.eventStorm=関連イベント件数がしきい値を厳密に超えた後のイベントストーム通知、dailySummary=サイト集約ジョブによって送信される日次サマリー。 null を許可: False 例: ["issue.add", "issue.modify", "issueReply.add", "issueUpgrade.noManager", "issueUpgrade.processTimeout", "issueUpgrade.eventStorm"]取得または入力方法: 以下で実際にサポートされるイベントタイプから選択し、必要な種類に対応する文字列を含めます。省略または [] の場合、これらのアクションは有効になりません。 |
|
| extend.upgradeCfg | json | 4種類のエスカレーションルールオブジェクトで、それぞれ設定できます。エスカレーションルールがない場合は省略または {} です。 null を許可: False 例: {"noManager": {"duration": 600, "notifyType": "once"}, "processTimeout": {"duration": 1800, "notifyType": "cycle", "cycleDuration": 600, "cycleTimes": 3}, "openProcessTimeout": {"duration": 900, "notifyType": "once"}, "eventStorm": {"exceedTimes": 60, "notifyType": "once"}}取得または入力方法: 先に notifyTypes で対応するエスカレーションタイプを有効にしてから、そのルールを入力します。ルールのみを入力してタイプを有効にしない場合、有効なエスカレーショントリガーは作成されません。 |
|
| name | string | Y | 必須の非空ポリシー名で、最大256文字です。変更時も送信必須です。 空文字列を許可: False null を許可: False 最大長: 256 例: 生产异常通知取得または入力方法: 通知ポリシー一覧で既存ポリシー名を確認し、現在のワークスペース内で未使用の名前を選択します。 |
| notificationScheduleUUIDs | array | 完全な対象スケジュールUUID配列。省略または [] の場合、すべてのスケジュール関連付けをクリアします。 null を許可: False 例: ["nsche_example"]取得または入力方法: 通知スケジュール一覧の content.data[].uuid から同一ワークスペースの通知スケジュールを取得します。1つのポリシーに複数のスケジュールを関連付けられます。 |
パラメータ補足¶
noManager は担当者なしの待機、processTimeout は Open/Working の連続処理タイムアウト、openProcessTimeout は Open のみのタイムアウトです。後者2項目は同じく issueUpgrade.processTimeout によって有効化されます。eventStorm は待機秒数ではなく関連イベント件数のしきい値を使用します。循環ルールでは cycleDuration と cycleTimes の両方を指定する必要があり、フィールドが欠けている場合は設定が保存されるだけで有効なルールが確立されない可能性があります。ネストされたフィールドは項目ごとに厳密に検証されないため、誤った型でも汎用的な内部エラーが返る可能性があります。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/issue/notification_policy/inpy_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"生产异常通知","notificationScheduleUUIDs":["nsche_example"],"extend":{"notifyTypes":["issue.add","issue.modify","issueReply.add","issueUpgrade.noManager","issueUpgrade.processTimeout","issueUpgrade.eventStorm"],"upgradeCfg":{"noManager":{"duration":600,"notifyType":"once"},"processTimeout":{"duration":1800,"notifyType":"cycle","cycleDuration":600,"cycleTimes":3},"openProcessTimeout":{"duration":900,"notifyType":"once"},"eventStorm":{"exceedTimes":60,"notifyType":"once"}}}}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | ポリシーレコード番号。作成レスポンスでは保存前に構築される場合 null になり得ます。操作には uuid を使用します。 |
| content.uuid | string | 通知ポリシーUUID。inpy_ で始まります。 |
| content.workspaceUUID | string | 所属ワークスペースUUID。 |
| content.name | string | ポリシー名。 |
| content.status | integer | レコードステータス。0=有効、2=無効、3=削除。一覧には未削除の有効および無効ポリシーが含まれます。 |
| content.creator | string | 作成呼び出し元の識別情報。 |
| content.updator | string | 最近の更新元。未更新の場合は空文字列。 |
| content.createAt | integer | 作成時刻(Unix秒)。 |
| content.updateAt | integer | 更新時刻(Unix秒)。未更新の場合は -1。 |
| content.deleteAt | integer | 削除時刻(Unix秒)。未削除の場合は -1。 |
| content.extend | object | 保存された通知範囲とエスカレーションルール。{} になり得ます。 |
| content.extend.notifyTypes | array<string> |
有効なアクションタイプ。 |
| content.extend.notifyTypes[] | string | 単一のアクションタイプ。具体的な作用はパラメータ表を参照してください。 |
| content.extend.upgradeCfg | object | トリガータイプ別に保存されたルール。 |
| content.extend.upgradeCfg.noManager | object | Issue 作成時に有効な担当者がおらず、担当者なし候補に入り、ステータスが Open/Working/Pending の場合、Issue 作成時から待機します。既存 Issue は担当者を削除しただけでは候補に再進入することが保証されません。正の整数秒で、60の倍数を入力します。有効化タイプは issueUpgrade.noManager で、未設定の場合は省略されます。 |
| content.extend.upgradeCfg.noManager.duration | integer | 初回待機秒数。 |
| content.extend.upgradeCfg.noManager.notifyType | string | once または cycle。この値が保存されていない場合は once として扱われます。 |
| content.extend.upgradeCfg.noManager.cycleDuration | integer | 循環間隔(秒)。cycle モードで使用します。 |
| content.extend.upgradeCfg.noManager.cycleTimes | integer | 循環トリガーの総回数上限。1~30で、初回を含みます。 |
| content.extend.upgradeCfg.processTimeout | object | Issue が Open/Working の状態で継続して未完了となっている時間。初回は作成時から計時します。Pending/Resolved/Closed から処理状態に再進入した場合、再進入後の状態記録から計時します。有効化タイプは issueUpgrade.processTimeout で、未設定の場合は省略されます。 |
| content.extend.upgradeCfg.processTimeout.duration | integer | 初回待機秒数。 |
| content.extend.upgradeCfg.processTimeout.notifyType | string | once または cycle。この値が保存されていない場合は once として扱われます。 |
| content.extend.upgradeCfg.processTimeout.cycleDuration | integer | 循環間隔(秒)。cycle モードで使用します。 |
| content.extend.upgradeCfg.processTimeout.cycleTimes | integer | 循環トリガーの総回数上限。1~30で、初回を含みます。 |
| content.extend.upgradeCfg.openProcessTimeout | object | Issue が Open のままの場合のみ有効で、最後のステータス変更時刻から計時します。ステータス記録がない場合は作成時刻から計時します。有効化タイプは issueUpgrade.processTimeout で、未設定の場合は省略されます。 |
| content.extend.upgradeCfg.openProcessTimeout.duration | integer | 初回待機秒数。 |
| content.extend.upgradeCfg.openProcessTimeout.notifyType | string | once または cycle。この値が保存されていない場合は once として扱われます。 |
| content.extend.upgradeCfg.openProcessTimeout.cycleDuration | integer | 循環間隔(秒)。cycle モードで使用します。 |
| content.extend.upgradeCfg.openProcessTimeout.cycleTimes | integer | 循環トリガーの総回数上限。1~30で、初回を含みます。 |
| content.extend.upgradeCfg.eventStorm | object | Issue に記録された eventCount が exceedTimes を厳密に超えた後にトリガーされます。Open/Working の状態では限定されず、完了済みの Issue も件数条件を満たす可能性があります。有効化タイプは issueUpgrade.eventStorm で、未設定の場合は省略されます。 |
| content.extend.upgradeCfg.eventStorm.exceedTimes | integer | 件数のしきい値。eventCount が厳密に超えた場合にのみトリガーされます。 |
| content.extend.upgradeCfg.eventStorm.notifyType | string | once または cycle。この値が保存されていない場合は once として扱われます。 |
| content.extend.upgradeCfg.eventStorm.cycleDuration | integer | 循環間隔(秒)。cycle モードで使用します。 |
| content.extend.upgradeCfg.eventStorm.cycleTimes | integer | 循環トリガーの総回数上限。1~30で、初回を含みます。 |
| content.extend.その他のフィールド | JSON | 保存元のその他の拡張フィールド。すべてが通知動作を制御できるわけではありません。 |
| content.notificationScheduleUUIDs | array<string> |
成功時の関連スケジュールUUID配列。関連付けがない場合は []。作成時にフィールドを省略すると500が返る可能性があり、成功時の null 構造として扱うべきではありません。 |
| content.notificationScheduleUUIDs[] | string | スケジュールUUID。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": 42,
"uuid": "inpy_example",
"workspaceUUID": "wksp_example",
"name": "生产异常通知",
"extend": {
"notifyTypes": [
"issue.add",
"issue.modify",
"issueReply.add",
"issueUpgrade.noManager",
"issueUpgrade.processTimeout",
"issueUpgrade.eventStorm"
],
"upgradeCfg": {
"noManager": {
"duration": 600,
"notifyType": "once"
},
"processTimeout": {
"duration": 1800,
"notifyType": "cycle",
"cycleDuration": 600,
"cycleTimes": 3
},
"openProcessTimeout": {
"duration": 900,
"notifyType": "once"
},
"eventStorm": {
"exceedTimes": 60,
"notifyType": "once"
}
}
},
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785430800,
"updateAt": 1785430860,
"deleteAt": -1,
"notificationScheduleUUIDs": [
"nsche_example"
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | トリガー条件 | メッセージまたはレスポンス説明 | 処理方法 |
|---|---|---|---|---|
| 404 | ft.ObjectNotExists | ポリシーが存在しない、削除済み、または現在の API Key ワークスペースに属していない | 指定されたオブジェクトが存在しません | 通知ポリシー一覧から本ワークスペースのUUIDを再取得します。 |
| 406 | ft.ParameterValidationFailed | リクエストフィールドが欠落している、またはフィールド値が宣言された検証条件に違反している | パラメータ解析に失敗しました | パラメータの位置、フィールド名、型、値を確認します。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効 | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正します。 |
| 400 | ft.JsonFormatError | JSON のトップレベルがオブジェクトではない | 一部の json ファイル形式エラー | 単一の JSON オブジェクトを送信します。 |
| 400 | ft.PolicySameNameExists | 現在のワークスペースに同名の未削除ポリシーが存在する(無効ポリシーを含む) | 同名の通知ポリシーがすでに存在します | 未使用の名前を選択します。タイムアウト後は、まず保存済みかどうかを確認します。 |
| 400 | ft.InvalidFieldValue | notifyType が once/cycle でない、または cycleTimes が1~30の範囲外 | フィールド {} の値: {} が無効 | ルールに従って notifyType と回数を入力します。ネストされたオブジェクトには正しい型を使用してください。 |
| 400 | ft.UpgradeTimeTooLarge | いずれかの時間型 duration が31622400秒を超えている | エスカレーション時間設定が大きすぎます。妥当なエスカレーショントリガー時間を設定してください | 待機時間を短縮します。最大31622400秒です。 |
| 400 | ft.InvalidUpgradeTimeDuration | 時間型 duration が60秒の整数倍ではない | エスカレーション時間設定は 60(s) の正の整数倍である必要があります | 正の整数分に60を掛けた秒数を使用します。 |
| 400 | ft.exceedTimesTooLarge | eventStorm.exceedTimes が31622400を超えている | 関連イベントのトリガー回数が大きすぎます。妥当なトリガー回数を設定してください | 31622400を超えない正の整数のイベント件数しきい値を使用します。 |
| 500 | ft.InternalServerError | notificationScheduleUUIDs を省略した場合、または関連付け保存、エスカレーションルール処理などの内部失敗。ポリシー本体はすでに保存されている可能性がある | 内部エラー | まずポリシー一覧で同名レコードが作成済みか確認します。作成リクエストでは notificationScheduleUUIDs 配列を明示的に指定してから、再試行するかどうかを判断します。 |