作成¶
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 を保持してください。 |