変更¶
POST /api/v1/notification_schedule/{notification_schedule_uuid}/modify
概要¶
通知スケジュールとその時間帯、有効期間、ローテーション順序を完全に更新します。
呼び出し前の確認と使用手順¶
まずスケジュール詳細から現在の設定を読み取り、その後、完全な必須フィールドを指定します。この操作は設定全体を置き換えます。timezone を省略すると Asia/Shanghai にリセットされ、extend を省略すると {} にクリアされます。部分更新として呼び出さないでください。タイムゾーン、時間帯、通知ターゲット、または extend を変更すると rotationUpdateAt がリセットされます。名前だけの変更ではリセットされません。まず通知先一覧またはワークスペースメンバー一覧から有効な通知ターゲットを取得し、スケジュールのタイムゾーンに合わせて同一日の HH:MM 時間帯を指定します。ローテーションを有効にする場合は rotationCycle を必ず渡し、notifyTargets の順序に従って各周期で1つのターゲットを使用します。ローテーションを無効にする場合は、すべてのターゲットが共同で有効になります。ローテーションは rotationUpdateAt を基準とします。 作成または変更が成功すると、当日のオンコールキャッシュがクリアされます。書き込みと後続処理は段階的に完了する場合があるため、タイムアウトまたは 500 の後は、まず一覧または詳細を確認し、保存済みかどうかを確かめてから再試行するかどうかを決め、重複作成を避けてください。無料プランワークスペースでメールアドレスを使用する場合、既存のワークスペースメンバーのメールアドレスのみサポートされます。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| notification_schedule_uuid | string | Y | 対象スケジュールの UUID。現在の API Key のワークスペースに属している必要があります。 例: nsche_example取得方法または入力方法: スケジュール一覧が返す content.data[].uuid から取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証資格情報。 例: <DF-API-KEY>取得方法または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| notifyTargets[*] | string | アカウントUUID、通知先UUID、またはメールアドレスのいずれか。 例: notify_example取得方法または入力方法: メンバーの場合はワークスペースメンバー一覧のアカウント UUID から取得し、通知先の場合は通知先一覧の uuid から取得するか、有効なメールアドレスを入力します。すべて文字列である必要があります。 |
|
| extend.effectiveTime.start | integer | 有効期間の開始秒数。0 または省略時は開始を制限しません。 例: 1785427200取得方法または入力方法: Unix 秒で開始境界を指定します。 |
|
| extend.effectiveTime.end | integer | 有効期間の終了秒数。0 または省略時は終了を制限しません。 例: 1788019200取得方法または入力方法: Unix 秒で終了境界を指定します。0 以外の場合は開始より前になってはいけません。 |
|
| end | string | Y | HH:MM。start より後である必要があります。終了分には59秒を加算します。日をまたぐ場合は別々のスケジュールに分割してください。 null を許可: False 最大長: 48 例: 18:00取得方法または入力方法: 選択したスケジュールのタイムゾーンに合わせて、同一日の終了時刻を選択します。 |
| extend | json | 完全な拡張設定。省略時は {} です。 null を許可: False 例: {"enableRotateNotification": false}取得方法または入力方法: ローテーションと全体の有効期間の必要性に応じて入力します。 |
|
| extend.effectiveTime | json | 全体の有効期間オブジェクト。省略時は永久有効を意味します。タイムスタンプの単位は秒で、通常10桁です。ミリ秒ではありません。 null を許可: False 例: {"start": 1785427200, "end": 1788019200}取得方法または入力方法: 業務上の有効期間を Unix 秒に変換します。JavaScript の Date.getTime() は1000で割って整数にします。 |
|
| extend.enableRotateNotification | boolean | ローテーションを有効にするかどうか。デフォルトは false です。 null を許可: False 例: false取得方法または入力方法: すべてのターゲットが共同でオンコールする場合は false、単一のターゲットをローテーションする場合は true を使用します。 |
|
| extend.rotationCycle | string | ローテーションを有効にする場合は明示的に指定する必要があります。day は暦日ごとにローテーションします。week は毎週月曜日に切り替わり、7日間の累積ではありません。month は自然月ごとに切り替わります。workDay は月曜日から金曜日のみを対象に営業日ごとにローテーションし、週末は適用されません。weekend は土曜日/日曜日のみを対象に日ごとにローテーションし、平日は適用されません。法定祝日は認識しません。rotationUpdateAt を基準とします。 null を許可: False 選択可能な値: ['day', 'week', 'month', 'workDay', 'weekend'] 例: day取得方法または入力方法: day、week、month、workDay、weekend から選択します。 |
|
| name | string | Y | 空でない名前。最大256文字。このワークスペース内で重複できません。 空文字列を許可: False null を許可: False 最大長: 256 例: 生产值班取得方法または入力方法: スケジュール一覧でこのワークスペース内の重複を確認してから入力します。 |
| notifyTargets | array | Y | 完全で順序付けられた文字列配列。ローテーションはこの順序に従います。空の配列は通知ターゲットがないことを示します。 null を許可: False 例: ["notify_example"]取得方法または入力方法: メンバーの場合はワークスペースメンバー一覧のアカウント UUID から取得し、通知先の場合は通知先一覧の uuid から取得するか、有効なメールアドレスを入力します。すべて文字列である必要があります。 |
| start | string | Y | HH:MM。00:00~23:59 の範囲で、end より前である必要があります。 null を許可: False 最大長: 48 例: 09:00取得方法または入力方法: 選択したスケジュールのタイムゾーンに合わせて、毎日の開始時刻を選択します。 |
| timezone | string | スケジュールのタイムゾーン。省略時はデフォルトで Asia/Shanghai です。 null を許可: False 最大長: 48 例: Asia/Shanghai取得方法または入力方法: 実際の業務タイムゾーンの IANA 識別子(Asia/Shanghai、UTC など)を選択します。 |
パラメータ補足説明¶
時間帯には終了分の最後の秒が含まれます。たとえば 18:00 は実際には 18:00:59 まで有効です。全体の effectiveTime は Unix 秒を使用します。例ではローテーションを無効にし、永久有効期間を使用しています。パラメータ表に従って完全なローテーション設定を追加できます。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/notification_schedule/nsche_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"生产值班","timezone":"Asia/Shanghai","start":"09:00","end":"18:00","notifyTargets":["notify_example"],"extend":{"enableRotateNotification":false}}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 保存されたスケジュールエンティティと有効期間の表示情報。notifyTargetsInfos は含まれません。 |
| content.id | integer | データベースレコード番号。スケジュールの操作には uuid を使用します。 |
| content.uuid | string | スケジュール UUID。照会、変更、削除、および通知ポリシーからの参照に使用します。 |
| content.workspaceUUID | string | 所属するワークスペースの UUID。 |
| content.name | string | スケジュール名。 |
| content.timezone | string | このスケジュールが当日の時間帯と有効日を解釈するために使用する IANA タイムゾーン。 |
| content.start | string | 当日の開始時刻 HH:MM。 |
| content.end | string | 当日の終了時刻 HH:MM。終了分の最後の秒まで有効です。 |
| content.notifyTargets | array<string> |
メンバー、通知先UUID、またはメールアドレスを順序どおりに保存します。 |
| content.notifyTargets[] | string | acnt_ アカウント、notify_ 通知先、またはメールアドレス文字列。 |
| content.extend | object | 拡張設定。未設定の場合は {} にできます。 |
| content.extend.enableRotateNotification | boolean | ローテーションを有効にするかどうか。省略時は false として扱います。 |
| content.extend.rotationCycle | string | ローテーション有効時の周期。day は日ごと、week は月曜日ごと、month は自然月ごと、workDay は平日のみ日ごと、weekend は週末のみ日ごとです。祝日は認識しません。未設定の場合は省略できます。 |
| content.extend.effectiveTime | object | 全体の有効期間。未設定の場合は省略できます。 |
| content.extend.effectiveTime.start | integer | 有効期間の開始 Unix 秒。0 または省略時は制限しません。 |
| content.extend.effectiveTime.end | integer | 有効期間の終了 Unix 秒。0 または省略時は制限しません。 |
| content.rotationUpdateAt | integer | ローテーション計算の基準時刻(Unix 秒)。ローテーション関連の設定を変更するとリセットされます。 |
| content.status | integer | レコード状態。有効なレコードは 0 です。 |
| content.creator | string | 作成時の呼び出し元 ID。 |
| content.updator | string | 最終更新者の ID。未更新の場合は空文字列。 |
| content.createAt | integer | 作成時刻(Unix 秒)。 |
| content.updateAt | integer | 更新時刻(Unix 秒)。未更新の場合は -1。 |
| content.deleteAt | integer | 削除時刻(Unix 秒)。未削除の場合は -1。 |
| content.effectiveTimeInfos | object | 全体の有効期間の表示情報。一覧、作成、変更時のみ返されます。 |
| content.effectiveTimeInfos.timeStr | string | スケジュールのタイムゾーンに従って YYYY/MM/DD HH:MM:SS~YYYY/MM/DD HH:MM:SS にフォーマットされます。片側のみ未設定の場合は空、両側とも未設定の場合は文字列全体が空になります。 |
| content.effectiveTimeInfos.expired | boolean | 現在時刻が有効期間の終了を超えているかどうか。終了制限がない場合は false です。 |
| content.declaration | object または null | ワークスペースの共通宣言。 |
{
"code": 200,
"content": {
"id": 42,
"uuid": "nsche_example",
"workspaceUUID": "wksp_example",
"name": "生产值班",
"timezone": "Asia/Shanghai",
"start": "09:00",
"end": "18:00",
"notifyTargets": [
"notify_example"
],
"extend": {
"enableRotateNotification": false
},
"rotationUpdateAt": 1785427200,
"status": 0,
"creator": "wsak_example",
"updator": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"deleteAt": -1,
"effectiveTimeInfos": {
"timeStr": "",
"expired": false
},
"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.InvalidStartEndTimeFromat | 当日の時刻が範囲外、終了が開始より後でない、など | 無効な時間帯形式 | 有効な HH:MM を使用し、同一日で start が end より前になるようにしてください。解析できない終了形式は一般的な 500 になる場合もあります。 |
| 400 | ft.InvalidEffectiveTime | 0 以外の有効期間終了が開始より前 | 無効な有効期間 | 同じ単位の Unix 秒を使用し、終了境界を調整してください。 |
| 406 | ft.InvalidEmail | 通知ターゲットがアカウント/通知先UUIDでも有効なメールアドレスでもない | 無効なメールアドレス | 実際の UUID または有効なメールアドレス文字列を使用してください。 |
| 400 | ft.UnsupportExternalEmail | 無料プランワークスペースで、ワークスペースメンバーのメールアドレス以外を使用した | 無料プランワークスペースでは、通知先に外部メールアドレスを使用できません | ワークスペースに既存のメンバーのメールアドレスに変更するか、ワークスペースのバージョンが外部メールアドレスをサポートしていることを確認してください。 |
| 400 | ft.scheduleSameNameExists | 現在のワークスペースに同名の有効なスケジュールが既に存在する | 同名のスケジュールが既に存在します | 一覧を使用して重複を確認してから名前を変更してください。 |
| 400 | ft.MissingCustomParameters | ローテーションを有効にしたが rotationCycle を渡していない | {} フィールドが不足しています | サポートされている rotationCycle を同時に指定してください。 |
| 500 | ft.InternalServerError | 未知の IANA タイムゾーン、不正な実在日付、文字列でない通知ターゲット、解析できない時刻などによる内部障害 | 内部エラー | 呼び出し前にパラメータ表に従ってタイムゾーン、実在日付、HH:MM、文字列配列を検証してください。書き込み操作が失敗した場合は、まず詳細を確認して保存済みかどうかを確かめてから再試行するかどうかを決め、traceId を保持してください。 |
| 404 | ft.ObjectNotExists | スケジュールが存在しない、削除済み、または現在のワークスペースに属していない | 指定されたオブジェクトが存在しません | スケジュール一覧から有効な UUID を再コピーしてください。 |