追加¶
POST /api/v1/issue/notification_policy/add
概要¶
通知ポリシーを作成し、Issue 通知範囲、スケジュール、エスカレーションルールを設定します。
呼び出し前の準備と使用手順¶
作成時は、空でない name と notificationScheduleUUIDs:[] を最低限送信してください。この配列は実行時宣言では引き続き任意ですが、現在省略するとポリシー本体が保存された後に 500 が返る可能性があるため、クライアントは配列を明示的に渡す必要があります。スケジュールを関連付けない場合は [] を指定します。通知を発生させるには、実際のスケジュール、通知タイプ、および必要なエスカレーション設定を選択する必要があります。作成時には完全なエスカレーションルールを設定することを推奨します。ポリシーはコンソールで対象チャンネルに関連付け、有効な通知スケジュールを関連付ける必要があります。実際の受信者は、スケジュールのタイムゾーン、当日の時間帯、有効期間、ローテーション、通知ターゲットによって決まります。ポリシーの保存自体ではテスト通知はすぐに送信されません。エスカレーションはサイトの定期タスクによってチェックされ、正確なカウントダウンではありません。トリガー設定の作成または更新後に新しく作成された Issue のみがチェックされます。スケジュールにその時点で有効なターゲットがない場合でもトリガーが 1 回記録されることがあり、トリガー回数を配信回数として扱うことはできません。通知ターゲットと実際のメッセージの両方を確認してください。ポリシー本体、関連付け、エスカレーショントリガー設定は段階的に保存されます。失敗またはタイムアウト後は、まず詳細を取得して既存の変更を確認してから、再試行するかどうかを決定してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 | 実行時宣言では任意ですが、クライアントが作成する際は配列を明示的に送信してください。スケジュールがない場合は [] を渡します。省略すると、本体が保存された後に 500 が返る可能性があります。 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/add' \
-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": null,
"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": "",
"createAt": 1785430800,
"updateAt": -1,
"deleteAt": -1,
"notificationScheduleUUIDs": [
"nsche_example"
],
"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 ファイル形式エラー | 単一の 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 配列を明示的に指定してから、再試行するかどうかを決定します。 |