作成¶
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 | 無料または体験プランのワークスペースで電話通知先を作成 | ワークスペースでは电话通知先をサポートしていません |
現在のプランでサポートされている方式を選択してください。 |