コンテンツにスキップ

変更



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 を再コピーしてください。

フィードバック

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