コンテンツにスキップ

作成



POST /api/v1/notification_schedule/add

概要

通知スケジュールとその時間帯、有効期間、ローテーション順序を作成します。

呼び出し前の準備と使用手順

まず通知先リストまたはワークスペースメンバーリストから有効な通知先を取得し、スケジュールのタイムゾーンに合わせて同一日の HH:MM の時間帯を指定してください。ローテーションを有効にする場合は rotationCycle を必ず指定し、notifyTargets の順序に従って 1 周期ごとに 1 つの通知先を割り当てます。ローテーションを無効にする場合は、すべての通知先が同時に有効になります。ローテーションは rotationUpdateAt を基準とします。作成または変更が成功すると、当日のオンコールキャッシュがクリアされます。書き込みと後続処理は段階的に完了する場合があるため、タイムアウトまたは 500 が発生した場合は、まずリストまたは詳細を確認して保存済みかどうかを確かめてから再試行を判断し、重複作成を避けてください。無料プランまたは体験プランのワークスペースでメールアドレスを使用する場合、既存のワークスペースメンバーのメールアドレスのみサポートされます。

リクエストヘッダー

パラメータ名 型 必須 説明
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 秒で終了境界を指定します。非ゼロの場合は開始より早くできません。
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、1 つの通知先をローテーションする場合は true を使用します。
extend.rotationCycle string ローテーションを有効にする場合は必ず明示的に指定します。day は暦日単位でローテーションします。week は月曜日に切り替わり、累計 7 日ではありません。month は自然月で切り替わります。workDay は月曜日から金曜日のみを 1 営業日ごとにローテーションし、週末は有効ではありません。weekend は土曜日/日曜日のみを 1 日ごとにローテーションし、平日は有効ではありません。法定祝日は認識しません。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)。

パラメータ補足説明

時間帯には終了分の最後の 1 秒が含まれます。たとえば 18:00 の場合、実際には 18:00:59 まで有効です。全体の effectiveTime は Unix 秒を使用します。例ではローテーションを無効にし、無期限の有効期間を使用しています。パラメータ表に従って完全なローテーション設定を追加できます。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/notification_schedule/add' \
  -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 または null データベースの番号。作成時はまだ割り当てられていない場合があります。リソースの操作には 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。終了分の最後の 1 秒まで有効です。
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 作成した呼び出し元の識別情報。
content.updator string 最終更新者の識別情報。未更新の場合は空文字列。
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": null,
    "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": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "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 非ゼロの終了有効期間が開始より早い 無効な有効時間 同じ単位の Unix 秒を使用し、終了境界を調整してください。
406 ft.InvalidEmail 通知先がアカウント/通知先 UUID でも有効なメールアドレスでもない 無効なメールアドレス 実際の UUID または有効なメールアドレス文字列を使用してください。
400 ft.UnsupportExternalEmail 無料または体験プランのワークスペースで、ワークスペースメンバーのメールアドレス以外のメールアドレスを使用 体験版ワークスペースでは、通知先に外部メールアドレスを使用できません ワークスペースに既存のメンバーのメールアドレスに変更するか、ワークスペースのプランが外部メールアドレスをサポートしているか確認してください。
400 ft.scheduleSameNameExists 現在のワークスペースに同名の有効なスケジュールが既に存在 同名のスケジュールが既に存在します リストで重複を確認してから名前を変更してください。
400 ft.MissingCustomParameters ローテーションを有効にしたが rotationCycle を渡していない {} フィールドが欠落 サポートされている rotationCycle を併せて指定してください。
500 ft.InternalServerError 不明な IANA タイムゾーン、不正な実在日付、文字列以外の通知先、解析できない時刻などによる内部エラー 内部エラー 呼び出し前にパラメータ表に従ってタイムゾーン、実在日付、HH:MM、文字列配列を検証してください。書き込み操作が失敗した場合は、まず詳細を照会して保存済みかどうかを確認してから再試行を判断し、traceId を保持してください。

フィードバック

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