コンテンツにスキップ

作成



POST /api/v1/notify_object/create

概要

ワークスペースの通知先と通知設定を作成します。

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

通知方式に応じて type と optSet を選択します。mailGroup/sms/vms はメンバーまたはチームの UUID を使用し、ボットはプラットフォームから webhook を取得します。HTTP コールバックは url を使用します。保存に成功したことは通知設定が保存されたことのみを示し、ボットまたは HTTP 受信側が通知を受信済みであることを意味しません。例のアドレスは実際に使用可能なアドレスに置き換える必要があります。作成後、uuid をアラートポリシーで使用できます。重複して作成すると名前重複で失敗するため、タイムアウト後はまず一覧で確認してください。

リクエストヘッダー

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

Body リクエストパラメータ

パラメータ名 型 必須 説明
permissionSet[*] string 単一のロール、メンバー、またはチームの識別子文字列。* はオブジェクトレベルの操作制限を解除しますが、API 認証を通過する必要があります。
例: wsAdmin
取得方法または入力方法: メンバーはワークスペースメンバー一覧のアカウント UUID、チームはメンバーグループ一覧の group_ UUID、ロールはロール一覧のロール UUID または既存のロール識別子(wsAdmin など)を使用します。表示名は入力しないでください。
optSet.webhook string ボット、Slack、Teams、Google Chat、Jira、ServiceNow で使用するコールバックアドレス。Jira/ServiceNow は有効な HTTPS である必要があり、URL のユーザー名/パスワード、フラグメント、空白を含めることはできません。アドレスはサイトのドメイン名解決およびイントラネットポリシーの制限を受けます。
例: https://hooks.example.com/notify
取得方法または入力方法: 対象プラットフォームのボット、Workflow、Jira、または ServiceNow の統合設定でコールバックアドレスを取得します。
optSet.secret string dingTalkRobot/feishuRobot のオプションの署名キー。Jira では auth_type=secret の場合に必須です。Jira では同一の認証情報での更新時に省略すると保持され、その他のボットでは optSet を置き換える場合に再度指定する必要があります。
例: <robot-or-jira-secret>
取得方法または入力方法: DingTalk/Lark ボットの署名設定から取得するか、Jira 受信側の取り決めに従って設定します。
optSet.url string HTTPRequest/simpleHTTPRequest の必須かつ空でないコールバックアドレス。ドメイン名解決およびイントラネットポリシーの制限を受けます。
例: https://receiver.example.com/alerts
取得方法または入力方法: アラートの HTTP リクエストを受信できる実際のサービスアドレスを用意します。
optSet.to array<string> mailGroup、sms、vms の受信メンバー/チーム UUID 配列。メンバー情報に対応するメールアドレスまたは電話番号を設定する必要があります。任意のメールアドレス/電話番号文字列の配列ではありません。
例: ["acnt_example"]
取得方法または入力方法: メンバー一覧またはメンバーグループ一覧から UUID を取得します。
optSet.to[*] string 単一のメンバーまたはチーム UUID。
例: acnt_example
取得方法または入力方法: ワークスペースメンバー一覧またはメンバーグループ一覧からメンバー/チーム UUID をコピーします。
optSet.refMembers array<string> HTTPRequest/simpleHTTPRequest の両方で文字列配列を受け取り検証しますが、現在実際に refMembersInfo に展開されて内容解析に参加するのは HTTPRequest のみです。simpleHTTPRequest ではこの展開を行いません。
例: ["acnt_example"]
取得方法または入力方法: ワークスペースメンバー一覧またはメンバーグループ一覧から関連付けるメンバー/チーム UUID を選択します。
optSet.refMembers[*] string 関連付けるメンバーまたはチーム UUID 文字列。
例: acnt_example
取得方法または入力方法: ワークスペースメンバー一覧またはメンバーグループ一覧からアカウント/チーム UUID をコピーします。
optSet.headersConfig object カスタムリクエストヘッダー設定。Jira/ServiceNow の headers とは異なります。読み取り API はその機密値を復元するため、返却データは保存前に適切に扱ってください。
例: {"isOpen": true, "items": [{"key": "X-Notify-Source", "value": "guance", "isSensitive": false}]}
取得方法または入力方法: HTTP 受信サービスの取り決めに従って入力します。HTTPRequest/simpleHTTPRequest にのみ適用されます。
optSet.headersConfig.isOpen boolean 設定が存在する場合はブール値を必須とし、true の場合のみカスタムヘッダーを送信します。
例: true
取得方法または入力方法: カスタムリクエストヘッダーを有効にする場合は true、無効にする場合は false を使用します。
optSet.headersConfig.items array<object> 設定が存在する場合は配列を必須とし、最大 50 項目です。isOpen=false でも項目を検証します。
例: [{"key": "X-Notify-Source", "value": "guance", "isSensitive": false}]
取得方法または入力方法: 受信側で必要なリクエストヘッダー一覧を入力し、不要な場合は [] を渡します。
optSet.headersConfig.items[*] object 単一のカスタムリクエストヘッダーオブジェクト。
例: {"key": "X-Notify-Source", "value": "guance", "isSensitive": false}
取得方法または入力方法: 各ヘッダーは key/value/isSensitive の 3 つのフィールドを使用します。
optSet.headersConfig.items[*].key string 空でない文字列。前後の空白を除去した後、最大 256 文字。大文字小文字を区別せず重複排除します。
例: X-Notify-Source
取得方法または入力方法: 受信側で指定された HTTP ヘッダー名を使用します。
optSet.headersConfig.items[*].value string 空でない文字列。最大 4096 文字。
例: guance
取得方法または入力方法: 受信側で必要な値を入力します。認証情報は管理された設定からのみ取得してください。
optSet.headersConfig.items[*].isSensitive boolean 必須のブール値。true の値は保存時に暗号化され、詳細と一覧では元の値が復元されます。
例: false
取得方法または入力方法: 認証情報その他の機密値には true を使用します。
optSet.bodyTemplate string カスタムリクエストボディテンプレートは HTTPRequest のみサポートし、文字列は最大 5120 文字です。空文字列または null は未設定を意味し、空白のみの場合は有効になりません。保存時は型と長さのみを検証し、テンプレート構文や変数は検証しません。実際の送信はサイトのテンプレート機能に依存するため、実際のアラートで検証する必要があります。simpleHTTPRequest は空でないテンプレートをサポートしません。
例: {"title":"告警通知"}
取得方法または入力方法: HTTP 受信側の取り決めに従ってテキストテンプレートを提供し、実際のアラートでプレースホルダーと内容形式を検証してください。
optSet.token string telegramBot では必須かつ空でありません。Jira/ServiceNow の auth_type=bearer の認証情報。
例: <telegram-or-bearer-token>
取得方法または入力方法: telegramBot では Bot 管理で作成した Token を使用し、Jira/ServiceNow の bearer では受信側から割り当てられた Token を使用します。
optSet.chat_id string telegramBot では必須の対象チャット ID 文字列。
例: -1000000000000
取得方法または入力方法: Telegram の対象チャットから chat_id を確認し、文字列として送信します。
optSet.message_thread_id string telegramBot のオプションのトピック ID。存在する場合は文字列です。
例: 123
取得方法または入力方法: Telegram フォーラムのトピックが必要な場合、対象トピックから取得します。
optSet.auth_type string または null Jira/ServiceNow のみ。null は独立した認証ヘッダーを生成せず、basic、bearer、api_key をすべてサポートします。secret は Jira のみサポートします。省略時は Jira が secret、ServiceNow が basic をデフォルトとします。
例: bearer
取得方法または入力方法: Jira または ServiceNow の受信側がサポートする認証方式を選択します。
optSet.username string Jira/ServiceNow の basic 認証ユーザー名。空でなく、コロンまたは改行を含めることはできません。
例: notify-integration
取得方法または入力方法: 受信側の統合アカウントから取得します。
optSet.password string Jira/ServiceNow の basic 認証パスワード。空でなく、改行を含みません。同一の認証情報での更新時に省略すると保持されます。
例: <integration-password>
取得方法または入力方法: 受信側の統合アカウントから取得します。
optSet.api_key_header string Jira/ServiceNow の api_key 認証ヘッダー名。Content-Type にはできません。
例: X-API-Key
取得方法または入力方法: 受信側の取り決めに従って有効な HTTP ヘッダー名を選択します。
optSet.api_key string Jira/ServiceNow の api_key 認証情報。空でなく、改行を含みません。
例: <integration-api-key>
取得方法または入力方法: 受信側で生成または割り当てられた API Key を使用します。
optSet.headers object Jira/ServiceNow のみ。ヘッダー名は有効で、大文字小文字を区別せず重複せず、値に改行を含みません。Content-Type は application/json のみです。同一の認証情報での更新時に省略すると元のヘッダーを保持し、{} でクリアします。読み取り時は値がマスクされ空文字列になります。
例: {"X-Source": "guance"}
取得方法または入力方法: Jira/ServiceNow 受信側で必要なカスタムヘッダーを指定します。キーはヘッダー名、値は文字列です。
optSet.headers.动态键 string カスタムヘッダーの文字列値。更新時に同名の空値は同一の認証情報の旧値を保持できます。新しいヘッダーは空値にできません。
例: guance
取得方法または入力方法: 対象プラットフォームで必要な実際のヘッダー名(X-Source など)を使用します。
name string Y 通知先名。Jira/ServiceNow では空白を除去した後に空でなく、長さが 200 以下である必要があります。その他のタイプでは、空でない識別可能な名前を使用することを推奨します。
null を許可: False
例: 生产回调
取得方法または入力方法: 通知先一覧で検索して重複名を除外したうえで入力します。
openPermissionSet boolean カスタム操作権限を有効にするか。作成時のデフォルトは false、変更時に省略すると保持されます。作成者と Owner、および詳細設定に該当する主体は別途許可される場合があります。
null を許可: False
例: false
取得方法または入力方法: デフォルトでは API 権限を継承します。オブジェクトレベルの制限が必要な場合は true に設定し、permissionSet を構成します。
optSet json 通知タイプに応じた完全な JSON オブジェクトを指定します。作成時は明示的に指定する必要があります。通常のタイプでは変更時に全体を置き換え、Jira/ServiceNow では同一の認証情報のルールに従って認証情報を保持します。
null を許可: False
例: {"url": "https://receiver.example.com/alerts"}
取得方法または入力方法: type に応じて以下の表の対応する設定を選択し、受信プラットフォームまたはメンバー一覧から実際の値を取得します。
permissionSet array カスタムで操作可能な主体の完全な配列。変更時は全体を置き換え、[] でクリアします。特殊値 * は、API 認証を通過したすべての主体がこのオブジェクトレベルのチェックを通過できるようにしますが、匿名アクセスを開放するものではありません。
null を許可: False
例: ["wsAdmin"]
取得方法または入力方法: メンバーはワークスペースメンバー一覧のアカウント UUID、チームはメンバーグループ一覧の group_ UUID、ロールはロール一覧のロール UUID または既存のロール識別子(wsAdmin など)を使用します。表示名は入力しないでください。
type string Y 必須で、null 以外のサポート対象通知タイプである必要があります。trigger のデフォルト値はありません。
null を許可: True
選択可能な値: ['dingTalkRobot', 'HTTPRequest', 'wechatRobot', 'mailGroup', 'feishuRobot', 'sms', 'vms', 'simpleHTTPRequest', 'jiraWebhook', 'serviceNowWebhook', 'slackIncomingWebhook', 'teamsWorkflowWebhook', 'googleChatWebhook', 'telegramBot']
例: HTTPRequest
取得方法または入力方法: 対象の通知プラットフォームに応じて列挙値から選択します。HTTPRequest は HTTP コールバック、simpleHTTPRequest は簡易 HTTP コールバックです。

パラメータ補足説明

Jira/ServiceNow の元のパスワード、API Key、Token、カスタムヘッダー値は返却されません。has* と credentialsRequired を使用して設定済みかどうかを判断します。その他の従来のボットおよび HTTP 設定では、元の機密値が返却される場合があります。返却内容の全体を第三者に転送しないでください。

リクエスト例

curl --request POST 'https://openapi.guance.com/api/v1/notify_object/create' \
  -H 'DF-API-KEY: <DF-API-KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{"type":"HTTPRequest","name":"生产回调","optSet":{"url":"https://receiver.example.com/alerts"}}'

レスポンス

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

フィールド 型 説明
content object 保存された通知先レコード。一覧/詳細のアカウント概要と権限判定は含みません。
content.id integer または null データベース番号。作成レスポンスではまだ割り当てられていない場合があり、後続の操作では uuid を使用します。
content.uuid string 通知先 UUID。
content.workspaceUUID string 所属ワークスペース UUID。
content.name string 通知先名。
content.type string 通知タイプ。旧 Jira/ServiceNow の保存エイリアスは jiraWebhook/serviceNowWebhook に正規化されます。
content.optSet object type に対応する通知設定。具体的なフィールドは以下を参照してください。未設定のフィールドは省略できます。
content.openPermissionSet boolean このオブジェクトのカスタム操作権限を有効にするか。
content.permissionSet array<string> オブジェクトの操作を許可するロール、メンバー、チームの識別子配列。
content.permissionSet[] string 単一の権限主体識別子。
content.autoDisableAt integer 自動無効化時刻(Unix 秒)。自動無効化されていない場合は -1。
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.optSet.webhook string ボット、Slack、Teams、Google Chat、Jira、ServiceNow で使用するコールバックアドレス。Jira/ServiceNow は有効な HTTPS である必要があり、URL のユーザー名/パスワード、フラグメント、空白を含めることはできません。アドレスはサイトのドメイン名解決およびイントラネットポリシーの制限を受けます。
content.optSet.secret string DingTalk/Lark などのボットは元の署名キーを返す場合があります。Jira は元のキーを返さず、hasSecret フラグを使用します。
content.optSet.url string HTTPRequest/simpleHTTPRequest の必須かつ空でないコールバックアドレス。ドメイン名解決およびイントラネットポリシーの制限を受けます。
content.optSet.to array<string> mailGroup、sms、vms の受信メンバー/チーム UUID 配列。メンバー情報に対応するメールアドレスまたは電話番号を設定する必要があります。任意のメールアドレス/電話番号文字列の配列ではありません。
content.optSet.to[] string 単一のメンバーまたはチーム UUID。
content.optSet.refMembers array<string> HTTPRequest/simpleHTTPRequest の両方で文字列配列を受け取り検証しますが、現在実際に refMembersInfo に展開されて内容解析に参加するのは HTTPRequest のみです。simpleHTTPRequest ではこの展開を行いません。
content.optSet.refMembers[] string 関連付けるメンバーまたはチーム UUID 文字列。
content.optSet.headersConfig object カスタムリクエストヘッダー設定。Jira/ServiceNow の headers とは異なります。読み取り API はその機密値を復元するため、返却データは保存前に適切に扱ってください。
content.optSet.headersConfig.isOpen boolean 設定が存在する場合はブール値を必須とし、true の場合のみカスタムヘッダーを送信します。
content.optSet.headersConfig.items array<object> 設定が存在する場合は配列を必須とし、最大 50 項目です。isOpen=false でも項目を検証します。
content.optSet.headersConfig.items[] object 単一のカスタムリクエストヘッダーオブジェクト。
content.optSet.headersConfig.items[].key string 空でない文字列。前後の空白を除去した後、最大 256 文字。大文字小文字を区別せず重複排除します。
content.optSet.headersConfig.items[].value string 空でない文字列。最大 4096 文字。
content.optSet.headersConfig.items[].isSensitive boolean 必須のブール値。true の値は保存時に暗号化され、詳細と一覧では元の値が復元されます。
content.optSet.bodyTemplate string カスタムリクエストボディテンプレートは HTTPRequest のみサポートし、文字列は最大 5120 文字です。空文字列または null は未設定を意味し、空白のみの場合は有効になりません。保存時は型と長さのみを検証し、テンプレート構文や変数は検証しません。実際の送信はサイトのテンプレート機能に依存するため、実際のアラートで検証する必要があります。simpleHTTPRequest は空でないテンプレートをサポートしません。
content.optSet.token string telegramBot は設定された Bot Token を返します。Jira/ServiceNow は bearer 認証情報を返さず、hasToken フラグを使用します。
content.optSet.chat_id string telegramBot では必須の対象チャット ID 文字列。
content.optSet.message_thread_id string telegramBot のオプションのトピック ID。存在する場合は文字列です。
content.optSet.auth_type string または null Jira/ServiceNow のみ。null は独立した認証ヘッダーを生成せず、basic、bearer、api_key をすべてサポートします。secret は Jira のみサポートします。省略時は Jira が secret、ServiceNow が basic をデフォルトとします。
content.optSet.username string Jira/ServiceNow の basic 認証ユーザー名。空でなく、コロンまたは改行を含めることはできません。
content.optSet.api_key_header string Jira/ServiceNow の api_key 認証ヘッダー名。Content-Type にはできません。
content.optSet.headers object Jira/ServiceNow のみ。ヘッダー名は有効で、大文字小文字を区別せず重複せず、値に改行を含みません。Content-Type は application/json のみです。同一の認証情報での更新時に省略すると元のヘッダーを保持し、{} でクリアします。読み取り時は値がマスクされ空文字列になります。
content.optSet.headers.动态键 string カスタムヘッダーの文字列値。更新時に同名の空値は同一の認証情報の旧値を保持できます。新しいヘッダーは空値にできません。
content.optSet.hasSecret boolean Jira の secret モードのみ。署名キーが設定済みかどうか。
content.optSet.hasPassword boolean Jira/ServiceNow の basic モードのみ。パスワードが設定済みかどうか。
content.optSet.hasToken boolean Jira/ServiceNow の bearer モードのみ。Token が設定済みかどうか。
content.optSet.hasApiKey boolean Jira/ServiceNow の api_key モードのみ。Key が設定済みかどうか。
content.optSet.hasHeaderValues object Jira/ServiceNow のみ。返却される各ヘッダーについて、空でない値が保存済みかどうかを示します。
content.optSet.hasHeaderValues.动态键 boolean ヘッダー名に対応する設定状態。
content.optSet.deliveryStatus string Jira/ServiceNow の設定表示識別子。現在は configured で、実際の配信成功を意味しません。
content.optSet.credentialsRequired boolean Jira/ServiceNow で、現在の認証方式に必要な認証情報またはヘッダー値がまだ不足しているかどうか。
content.declaration object または null ワークスペース共通宣言。
{
  "code": 200,
  "content": {
    "id": null,
    "uuid": "notify_example",
    "workspaceUUID": "wksp_example",
    "name": "生产回调",
    "type": "HTTPRequest",
    "optSet": {
      "url": "https://receiver.example.com/alerts"
    },
    "openPermissionSet": false,
    "permissionSet": [],
    "autoDisableAt": -1,
    "status": 0,
    "creator": "wsak_example",
    "updator": "",
    "createAt": 1785427200,
    "updateAt": -1,
    "deleteAt": -1,
    "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.NofityObjectNameRepeat 同一ワークスペースに同名の有効または無効な通知先が既に存在 同名の通知先が既に存在します 既存の名前を検索し、未使用の名前を使用してください。
406 ft.InvalidParameter Jira/ServiceNow の名前、アドレス、認証モード、認証情報、またはリクエストヘッダーがルールに適合しない パラメータ {} が無効です エラーで指摘されたフィールドをパラメータ表に従って修正してください。読み取り専用の has* フラグを秘密値の代わりに返すことはできません。
406 ft.InvalidType 通知タイプがサポート対象外、または null が渡された 無効な type 作成パラメータの列挙値から null 以外のタイプを使用し、trigger や旧エイリアスを使用して作成しないでください。
406 ft.InvalidAddress コールバックドメイン名を解決できない ドメイン名 {} を解決できません 解決可能な対象コールバックドメイン名を使用し、サイトの DNS を確認してください。
406 ft.IntranetError コールバックアドレスがサイトのイントラネット制限に該当 イントラネットアドレスは入力できません サイトで許可されたコールバック先を使用するか、管理者にアドレスポリシーを確認してください。
500 ft.InternalServerError 設定フィールドの欠落または型の不正、データベースまたはキャッシュ処理の失敗 内部エラー 本ページに従って対応する通知タイプの設定を確認し、traceId を記録してください。書き込み操作が失敗した後は、対象が保存済みかどうかを先に確認してから再試行してください。
403 ft.ForbiddenFreeEditionWorkspace ワークスペースのプランで選択した通知タイプの作成が許可されていない 無料プランのワークスペースではこの機能をサポートしていません。商用プランにアップグレードすると制限を解除できます ワークスペースプランの通知方式の機能を確認し、サポートされているタイプを選択するかプランをアップグレードしてください。
406 ft.UnsupportShortMessage 無料または体験プランのワークスペースで SMS 通知先を作成 無料プランのワークスペースでは短信通知先をサポートしていません 現在のプランでサポートされている方式を選択してください。
406 ft.UnsupportOnCall 無料または体験プランのワークスペースで電話通知先を作成 ワークスペースでは电话通知先をサポートしていません 現在のプランでサポートされている方式を選択してください。

フィードバック

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