コンテンツにスキップ

作成



POST /api/v1/monitor/mute/create

概要

現在のワークスペースにイベント通知ミュートルールを作成します。単発のメンテナンスウィンドウと、タイムゾーンに基づく繰り返しウィンドウをサポートします。

呼び出し前の確認と使用手順

実際の範囲を確定してから完全な設定を送信します。custom はイベント条件を、checker はモニター/SLO 識別子を、alertPolicy はアラートポリシー識別子を、tag はモニタータグ識別子を使用します。範囲とイベント条件は共同でミュート対象を限定します。

単発の場合は repeatTimeSet=0 を使用し、有限の startTime/endTime を明示的に指定することを推奨します。繰り返しの場合は 1 を使用し、startTime、repeatCrontabSet の 5 フィールド、正の crontabDuration、repeatExpireTime を完全に指定します。永続的な繰り返しには文字列 "0" を渡します。期限値を省略しても、自動的に永続的な繰り返しにはなりません。

ルールは一致したイベントの通知ミュートを制御しますが、イベントとモニタリングデータは引き続き元のフローで処理されます。muteIncident はインシデント通知の拡張機能であり、現在の公開書き込みパラメータには含まれていません。調整が必要な場合はコンソールで操作してください。内部パラメータを公開リクエストのフィールドとして送信しないでください。

保存後、非同期タスクによって実行キャッシュとルール通知が更新されます。成功は同期やメッセージ配信が直ちに完了したことを意味しません。現在アクティブなルールを変更すると、設定済みの通知先へ再度通知される可能性があり、新しく追加した通知先だけに通知されることは保証されません。失敗した場合は、まずルールと有効化状態を確認してください。

notifyTargets が空の場合、ルール設定通知は送信されません。有効な通知先を設定する場合は、必ず notifyMessage も指定してください。notifyTimeStr の空値は即時通知の意図を表しますが、送信されるかどうかはタスクの時間帯と状態に制約されます。終了時刻のない単発ルールは実行上有効ですが、現在の設定通知タスクでは終了済みとして扱われます。

リクエストヘッダー

パラメータ名 型 必須 説明
DF-API-KEY string Y ワークスペースの OpenAPI 認証情報。
例: <DF-API-KEY>
取得方法または入力方法: 対象ワークスペースの API キー管理から、この操作権限を持つ OpenAPI キーを取得します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
muteRanges[*] json 単一の範囲オブジェクトです。一致判定は UUID フィールドによって決まり、name/type は表示情報です。通常、1 項目には 1 種類のリソースキーのみを指定します。
例: {"checkerUUID": "rul_example", "name": "生产接口监控"}
取得方法または入力方法: 同じワークスペースのモニター/SLO、アラートポリシー、またはモニタータグ管理から対応する UUID を取得します。表示名を安定した識別子の代わりに使用しないでください。
muteRanges[*].checkerUUID string モニター UUID です。checker 範囲でよく使用されます。
例: rul_example
取得方法または入力方法: このワークスペースのモニター、インテリジェントモニタリング、またはインテリジェントインスペクション設定から rul_ UUID を取得します。
muteRanges[*].sloUUID string SLO 識別子です。実行時に対応する SLO 検出モニターへマッピングされます。有効な検出関係がない場合、有効になることは保証されません。
例: monitor_example
取得方法または入力方法: このワークスペースの SLO 一覧から monitor_ UUID を取得します。
muteRanges[*].alertPolicyUUID string アラートポリシー識別子です。alertPolicy 範囲で使用します。
例: altpl_example
取得方法または入力方法: アラートポリシー一覧 の content.data[].uuid から取得します。
muteRanges[*].tagUUID string モニタータグ識別子です。実行時にはタグ名によってイベントの df_label を照合します。
例: tag_example
取得方法または入力方法: モニタータグ管理からタグ UUID を取得します。任意のイベントフィールド値ではありません。
muteRanges[*].name string クライアント側の表示名です。UUID の代わりにはなりません。
例: 生产接口监控
取得方法または入力方法: 対応するリソースの表示名を使用します。省略可能です。
muteRanges[*].type string 表示用の型です。実際の範囲の意味はトップレベルの type と UUID フィールドによって決まります。
例: 监控器
取得方法または入力方法: クライアントの必要に応じてリソースの表示型を保持します。省略可能です。
tags.字段 array このフィールドで一致させる実際の値の配列です。
例: ["production"]
取得方法または入力方法: キーには env などの実際のイベントフィールドを使用し、値は配列で指定することを推奨します。
tags.字段[*] string 個々の一致値です。実際のデータ型に応じて選択します。
例: production
取得方法または入力方法: イベント内の同じフィールドの値を取得します。
notifyTargets[*] json 単一の通知先グループです。type と to を使用します。
例: {"type": "mail", "to": ["acnt_example"]}
取得方法または入力方法: アカウントはワークスペースメンバーから acnt_ UUID を取得し、チームはこのワークスペースのチーム管理から group_ UUID を取得し、通知先は通知先一覧から notify_ UUID を取得します。
notifyTargets[*].type string 通知先の型です。実行タスクがサポートする mail/notifyObject/memberGroup を選択します。不明な型は保存できても有効な通知を生成しない可能性があります。
例: mail
取得方法または入力方法: メールアカウントには mail、通知先には notifyObject、チームメールには memberGroup を使用します。
notifyTargets[*].to array mail にはアカウント UUID、notifyObject には通知先 UUID、memberGroup にはチーム UUID を指定します。同じワークスペース内の有効なリソースのみを送信してください。
例: ["acnt_example"]
取得方法または入力方法: アカウントはワークスペースメンバーから acnt_ UUID を取得し、チームはこのワークスペースのチーム管理から group_ UUID を取得し、通知先は通知先一覧から notify_ UUID を取得します。
notifyTargets[*].to[*] string 対応する型の単一 UUID です。メールアドレスをそのままアカウント UUID として扱わないでください。
例: acnt_example
取得方法または入力方法: アカウントはワークスペースメンバーから acnt_ UUID を取得し、チームはこのワークスペースのチーム管理から group_ UUID を取得し、通知先は通知先一覧から notify_ UUID を取得します。
declaration.自定义字段 JSON カスタム宣言の内容です。ルールの一致判定や認可を変更しません。
例: MAINT-EXAMPLE
取得方法または入力方法: 独自の業務に合わせてフィールド名と値を定義します。
crontabDuration int 繰り返しモードでは条件付きで必須です。0 より大きい必要があります。単発モードでは endTime を制御しません。
null を許可: False
例: 3600
取得方法または入力方法: 各ミュートウィンドウの継続時間を正の整数秒で指定します。たとえば 3600 は 1 時間です。
declaration json 任意のルールカスタム宣言オブジェクトです。変更時に省略すると保持され、{} でクリアされます。単一ルールレスポンスの content.declaration はこのフィールドであり、ワークスペースの共通宣言によって上書きされることはありません。
null を許可: False
例: {"ticket": "MAINT-EXAMPLE"}
取得方法または入力方法: 呼び出し元が、保持する必要のあるルール独自の説明または業務追跡識別子を入力します。
description string 任意の説明です。512 文字以下を推奨します。変更時に省略すると保持され、空文字列でクリアされます。
空文字列を許可: True
null を許可: False
例: 生产服务维护窗口。
取得方法または入力方法: メンテナンスの理由と影響範囲を説明します。
endTime string 単発の終了時刻です。作成時に省略または空文字列を指定すると end=-1 で保存され、終了を設定しないことを表します。変更時に省略すると保持されますが、空文字列を渡すと現在は内部エラーが返る可能性があります。単発ルールでは有限の終了時刻を明示的に指定することを推奨します。
空文字列を許可: True
null を許可: False
例: 2026/11/20 10:00:00
取得方法または入力方法: 単発ルールでは実際の終了時刻を startTime より後に指定します。
filterString string 任意のイベント属性条件です。宣言上の最大長は 2048 文字ですが、現在の保存容量はより短いため、1024 文字以下を推奨します。空でない場合は tags より優先されます。変更時に省略すると保持され、空文字列でクリアされます。
空文字列を許可: True
null を許可: False
最大長: 2048
例: service:checkout-api
取得方法または入力方法: FilterString の構文に従って入力します。コンソールのイベントフィルターからコピーできます。
muteRanges array 完全な範囲の配列です。作成時に省略すると [] になります。変更時に省略した場合も元の範囲はクリアされます。各項目には型に応じた UUID を指定します。custom 範囲、tags、filterString がすべて空の場合、ワークスペース全体のイベント通知をミュートする可能性があるため、送信前に実際の範囲を確認してください。
null を許可: False
例: []
取得方法または入力方法: 同じワークスペースのモニター/SLO、アラートポリシー、またはモニタータグ管理から対応する UUID を取得します。表示名を安定した識別子の代わりに使用しないでください。
name string ルール名です。作成時と変更時は明示的に指定することを推奨します。省略した場合、作成時は範囲/タグ/条件に基づいて短い名前を生成でき、変更時は元の名前が保持されます。
null を許可: False
例: 生产维护静默
取得方法または入力方法: 業務担当者がメンテナンスウィンドウに名前を付けます。64 文字以下を推奨します。
notifyMessage string 任意の通知本文です。最大長は 3000 文字です。作成時、notifyTargets のいずれかの項目に空でない to が含まれる場合は、空でない内容を必ず指定してください。変更時は、通知先と内容が完全であることを自身で保証してください。
null を許可: False
最大長: 3000
例: 生产维护静默窗口已配置。
取得方法または入力方法: ミュートルールの通知内容を入力します。機密の認証情報を含めないでください。
notifyTargets array 任意のルール設定通知の通知先です。ミュートルール自体の通知に作用し、ミュートされたアラートの受信者ではありません。変更時に渡すと全体が置き換えられ、[] で削除され、省略すると保持されます。
null を許可: False
例: []
取得方法または入力方法: アカウントはワークスペースメンバーから acnt_ UUID を取得し、チームはこのワークスペースのチーム管理から group_ UUID を取得し、通知先は通知先一覧から notify_ UUID を取得します。
notifyTimeStr string 任意の通知時刻です。作成時に省略または空文字列を指定すると即時通知の意図として扱われ、変更時に省略すると保持され、空文字列にすると即時通知の意図に変更されます。実際の送信は有効な通知先、ルールの状態、時刻に依存します。通知をキャンセルするスイッチではありません。繰り返しルールでは、開始時刻との差分に応じて各周期で通知できます。
空文字列を許可: True
null を許可: False
例:
取得方法または入力方法: ルールの timezone に従って YYYY/MM/DD HH:MM:SS を入力します。
repeatCrontabSet object 繰り返しモードでは条件付きで必須の 5 段 Cron オブジェクトです。単発モードでは省略します。公開宣言にはオブジェクト型が示されていないため、ドキュメントでは実際のオブジェクトとして説明します。フィールドが欠けると無効な Cron が組み立てられる可能性があります。
null を許可: False
例: {"min": "0", "hour": "9", "day": "*", "month": "*", "week": "1-5"}
取得方法または入力方法: 繰り返しモードではルールの timezone に従って開始周期を選択し、以下の 5 つの文字列フィールドを完全に送信します。
repeatCrontabSet.day string 繰り返し時にこのフィールドの文字列を送信します。月内の日付で、1〜31 または * です。5 つのセグメントは直接連結され、実行可能な時点が存在するか検証されます。
null を許可: False
例: *
取得方法または入力方法: Cron 構文に従って選択します。たとえば * はすべて、カンマ/範囲は複数の時点を表します。
repeatCrontabSet.hour string 繰り返し時にこのフィールドの文字列を送信します。時間、0〜23 です。5 つのセグメントは直接連結され、実行可能な時点が存在するか検証されます。
null を許可: False
例: 9
取得方法または入力方法: Cron 構文に従って選択します。たとえば * はすべて、カンマ/範囲は複数の時点を表します。
repeatCrontabSet.min string 繰り返し時にこのフィールドの文字列を送信します。分、0〜59 です。5 つのセグメントは直接連結され、実行可能な時点が存在するか検証されます。
null を許可: False
例: 0
取得方法または入力方法: Cron 構文に従って選択します。たとえば * はすべて、カンマ/範囲は複数の時点を表します。
repeatCrontabSet.month string 繰り返し時にこのフィールドの文字列を送信します。月、1〜12 または * です。5 つのセグメントは直接連結され、実行可能な時点が存在するか検証されます。
null を許可: False
例: *
取得方法または入力方法: Cron 構文に従って選択します。たとえば * はすべて、カンマ/範囲は複数の時点を表します。
repeatCrontabSet.week string 繰り返し時にこのフィールドの文字列を送信します。曜日は Cron の週フィールドに従うか * を指定します。5 つのセグメントは直接連結され、実行可能な時点が存在するか検証されます。
null を許可: False
例: 1-5
取得方法または入力方法: Cron 構文に従って選択します。たとえば * はすべて、カンマ/範囲は複数の時点を表します。
repeatExpireTime string 繰り返しモードでは 0 または有効な期限日を明示的に指定してください。省略/空文字列は永続的な繰り返しを意味しません。-1 は単発の内部マーカーです。繰り返しで作成する際に省略すると単発として処理される可能性があり、繰り返しで変更する際に省略すると内部エラーになる可能性があります。
空文字列を許可: True
null を許可: False
例: 0
取得方法または入力方法: 永続的な周期には文字列 0 を指定します。有限の周期には timezone における YYYY/MM/DD HH:MM:SS を指定し、開始時刻より後であることを確認します。
repeatTimeSet int Y 必須の繰り返しモードです。実際の保存では repeatExpire/crontab で表現され、レスポンスで repeatTimeSet が固定して返されるわけではありません。
null を許可: False
例: 0
取得方法または入力方法: 1 回のみは 0、周期的な繰り返しは 1 を指定します。この 2 つの取り決められた値のみを使用してください。
startTime string 開始時刻です。YYYY/MM/DD HH:MM:SS。作成時に省略すると現在時刻を使用します。単発ルールの変更時に省略すると保持され、繰り返しに変更する場合は明示的に指定してください。
null を許可: False
例: 2026/11/20 09:00:00
取得方法または入力方法: メンテナンスウィンドウの開始時刻と選択した timezone に従って、ローカル時刻の文字列を入力します。
tags json 任意のフィールド値条件です。変更時に省略すると元の tags はクリアされます。空でない filterString は tags より優先されますが、muteRanges とは引き続き組み合わせられます。
null を許可: False
例: {"env": ["production"]}
取得方法または入力方法: env、host、service など、イベントの元のフィールド名と値から構成します。
timezone str Y 作成/変更時に必須のタイムゾーンです。ローカル時刻の解析と Cron の実行を制御します。無効なタイムゾーンまたは時刻文字列は、汎用的な内部エラーを返す可能性があります。
null を許可: False
例: Asia/Shanghai
取得方法または入力方法: Asia/Shanghai、UTC などの IANA タイムゾーンを使用します。時刻テキストはそのタイムゾーンで解釈されます。
type str Y 必須の型です。custom はカスタムイベント範囲、checker はモニター/SLO、alertPolicy はアラートポリシー、tag はモニタータグです。履歴一覧には monitor が出現する可能性がありますが、現在の公開書き込みではこの列挙値を受け付けません。
null を許可: False
選択可能な値: ['checker', 'alertPolicy', 'tag', 'custom']
例: custom
取得方法または入力方法: ミュート範囲に応じて custom/checker/alertPolicy/tag を選択します。

パラメータ補足説明

繰り返しウィンドウのリクエスト例:

curl --request POST '<Endpoint>/api/v1/monitor/mute/create' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"生产维护静默","description":"生产服务维护窗口。","type":"custom","muteRanges":[],"tags":{},"filterString":"service:checkout-api","notifyTargets":[],"repeatTimeSet":1,"timezone":"Asia/Shanghai","startTime":"2026/11/20 09:00:00","repeatCrontabSet":{"min":"0","hour":"9","day":"*","month":"*","week":"1-5"},"crontabDuration":3600,"repeatExpireTime":"0"}'

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/monitor/mute/create' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"name":"生产维护静默","description":"生产服务维护窗口。","type":"custom","muteRanges":[],"tags":{},"filterString":"service:checkout-api","notifyTargets":[],"repeatTimeSet":0,"timezone":"Asia/Shanghai","startTime":"2026/11/20 09:00:00","endTime":"2026/11/20 10:00:00"}'

レスポンス

HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。

フィールド 型 説明
content object 保存後の完全なルールエンティティおよびフォーマットされた時刻です。既存のルール declaration があり、共通宣言は追加挿入されません。
content.id integer ルールレコード番号です。操作には uuid を使用します。
content.uuid string mute_ ルール UUID。
content.workspaceUUID string 所属ワークスペース。
content.name string ルール名。
content.description string 説明。
content.type string custom/checker/alertPolicy/tag。履歴レコードには monitor も出現する可能性があります。
content.tags object 保存されたフィールド値条件。
content.tags.字段 JSON 対応するイベントフィールドの一致値。
content.filterString string イベント属性条件です。空でない場合は tags より優先されます。
content.muteRanges array<object> 保存された範囲配列です。各 UUID の意味はリクエストパラメータを参照してください。
content.muteRanges[].checkerUUID string または array モニター識別子です。履歴レコードでは配列の場合があります。
content.muteRanges[].sloUUID string または array SLO 識別子です。履歴レコードでは配列の場合があります。
content.muteRanges[].alertPolicyUUID string アラートポリシー UUID。
content.muteRanges[].tagUUID string または array モニタータグ UUID。
content.muteRanges[].name string 表示名です。省略可能です。
content.muteRanges[].type string 表示型です。省略可能です。
content.notifyTargets array<object> ミュートルールの通知先。
content.notifyTargets[].type string mail/notifyObject/memberGroup。
content.notifyTargets[].to array<string> 対応する型の UUID 配列です。
content.notifyTargets[].to[] string 単一の通知先 UUID。
content.notifyMessage string ミュートルールの通知本文。
content.notifyTime integer 通知時刻の Unix 秒です。-1 は即時通知の意図を表し、送信するかどうかは引き続きタスクが判断します。
content.notifyTimeStr string timezone に従ってフォーマットされた通知時刻です。即時通知の意図の場合は空文字列です。
content.start integer 開始 Unix 秒。
content.end integer 単発の終了 Unix 秒です。-1 は終了なし。
content.startTime string timezone における YYYY/MM/DD HH:MM:SS。
content.endTime string 同じ形式の終了時刻です。end=-1 の場合は空文字列。
content.repeatExpire integer -1 は単発、0 は永続的な繰り返し、正の値は周期の期限 Unix 秒です。
content.repeatExpireTime string -1/0、または timezone におけるフォーマットされた期限時刻。
content.crontab string 繰り返し時の 5 段 Cron 文字列です。単発では通常空です。
content.crontabDuration integer 各繰り返しウィンドウの継続秒数。
content.cycleNotifyAt integer 直近の周期設定通知時刻の Unix 秒です。未通知の場合は -1。
content.timezone string ルールのタイムゾーン。
content.declaration object ルールのカスタム宣言です。このワークスペースの共通宣言ではありません。
content.declaration.自定义字段 JSON 呼び出し元が保存したカスタム値。
content.muteIncident boolean インシデント通知も同時にミュートするかどうかです。現在の OpenAPI ではこの書き込みパラメータを宣言していません。作成時の既定値は false で、既存ルールはコンソールの設定を反映する場合があります。alertPolicy 範囲ではこのインシデント照合をサポートしません。
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.repeatCrontabSet object 一覧および繰り返しルール作成時に提供される Cron 逆解析オブジェクトです。変更レスポンスでは固定して提供されません。
content.repeatCrontabSet.min string 対応する Cron セグメント。
content.repeatCrontabSet.hour string 対応する Cron セグメント。
content.repeatCrontabSet.day string 対応する Cron セグメント。
content.repeatCrontabSet.month string 対応する Cron セグメント。
content.repeatCrontabSet.week string 対応する Cron セグメント。
{
  "code": 200,
  "content": {
    "id": 42,
    "uuid": "mute_example",
    "workspaceUUID": "wksp_example",
    "name": "生产维护静默",
    "description": "生产服务维护窗口。",
    "type": "custom",
    "tags": {},
    "filterString": "service:checkout-api",
    "muteRanges": [],
    "notifyTargets": [],
    "notifyMessage": "",
    "notifyTime": -1,
    "start": 1795136400,
    "end": 1795140000,
    "repeatExpire": -1,
    "cycleNotifyAt": -1,
    "crontab": "",
    "crontabDuration": 0,
    "declaration": {},
    "muteIncident": false,
    "timezone": "Asia/Shanghai",
    "status": 0,
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785430800,
    "updateAt": -1,
    "deleteAt": -1,
    "startTime": "2026/11/20 09:00:00",
    "endTime": "2026/11/20 10:00:00",
    "notifyTimeStr": "",
    "repeatExpireTime": "-1"
  },
  "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.muteStartEndError 単発の終了が開始より後ではないか、繰り返しの crontabDuration が 0 以下です ミュート開始時刻はミュート終了時刻より前である必要があります 前後関係を調整し、繰り返しウィンドウには正の秒数を指定してください。
406 ft.InvalidCrontabFormat Cron を解析できない、実行可能な時点がない、またはタイムゾーンによってスケジュールチェックが失敗しました 無効な crontab 形式 5 つの Cron 文字列フィールドと正しい timezone を完全に送信してください。
400 ft.ErrorFilterString イベント属性条件を解析できません filterString 解析失敗: {} コンソールで生成した有効な FilterString を使用するか、例に従って修正してください。
406 ft.ExceedTimestampLimit ミュート開始/終了/繰り返し期限の Unix 秒が 2147483647 を超えています 時刻が 2038-01-19 の制限を超えています これらの時刻を 2038-01-19 の上限以前に制限してください。ミリ秒を秒として扱わないでください。
500 ft.InternalServerError 繰り返しモードの必須フィールドが欠落している、時刻/タイムゾーンの形式が誤っている、配列要素の形状が誤っている、または保存/タスク処理に失敗しました 内部エラー 単発/繰り返しの完全な条件で自己確認してください。まず保存済みルールを確認してから再試行を判断し、継続して失敗する場合は traceId を提供してください。
406 ft.InvalidEventData 繰り返しルールを作成する際に repeatExpireTime から変換された正の Unix 秒が 10/13/16 桁でなく、時刻の正規化に失敗しました 無効なイベントデータ 正常に表現可能なメンテナンス日付を使用し、正の Unix 秒の長さを確認してください。この分岐は繰り返しルールの作成時のみ発生します。
406 ft.MissingNotifyMessage 作成時に通知先に空でない to が含まれていますが、notifyMessage が空です 通知先を選択した場合は通知内容を入力する必要があります 通知本文を提供するか、通知先配列をクリアしてください。

フィードバック

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