変更¶
POST /api/v1/notify_object/modify
概要¶
ワークスペースの通知先および通知設定を変更します。
呼び出し前の準備と使用手順¶
通知方式に応じて type と optSet を選択します。mailGroup/sms/vms はメンバーまたはチームの UUID を使用し、ボットはプラットフォームから webhook を取得します。HTTP コールバックは url を使用します。保存に成功したことは通知設定が保存されたことのみを意味し、ボットまたは HTTP 受信側が通知を受信済みであることを意味しません。例のアドレスは必ず実際に使用可能なアドレスに置き換えてください。notifyObjectUUID 以外の省略されたトップレベルフィールドは保持されます。通常タイプの optSet は全体が置き換えられるため、先に旧設定を読み取り、必要なフィールドをマージしてください。Jira/ServiceNow では webhook と認証方式、および秘密でない識別フィールドを再度指定する必要があります。同一アドレス、同一認証方式、同一 basic ユーザー名、または同一 API Key ヘッダー名の場合に限り、省略または空の秘密値は保持できます。識別情報を変更する場合は新しい認証情報を提供する必要があります。headers は同一識別の場合に省略すると保持され、{} でクリアされます。読み取り時にマスクされた空値を新しい認証情報と見なさないでください。type は変更できません。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| permissionSet[*] | string | 単一のロール、メンバー、またはチームの識別子文字列。* はオブジェクトレベルの操作制限を解除することを示しますが、引き続きインターフェースの認証を通過する必要があります。 例: 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/Feishu ボットの署名設定から取得するか、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 のいずれも文字列配列を受け取り検証しますが、現在 HTTPRequest のみが実際に refMembersInfo に展開されコンテンツ解析に参加します。simpleHTTPRequest ではこの展開は行われません。 例: ["acnt_example"]取得または入力方法: ワークスペースメンバー一覧またはメンバーグループ一覧から関連付けるメンバー/チーム UUID を選択します。 |
|
| optSet.refMembers[*] | string | 関連付けられたメンバーまたはチームの UUID 文字列。 例: acnt_example取得または入力方法: ワークスペースメンバー一覧またはメンバーグループ一覧からアカウント/チーム UUID をコピーします。 |
|
| optSet.headersConfig | object | カスタムリクエストヘッダー設定。Jira/ServiceNow の headers とは異なります。読み取りインターフェースはその機密値を復元するため、保存前に返却データを適切に扱ってください。 例: {"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 | 通知先の名前。Jira/ServiceNow では空白除去後が非空かつ長さ 200 以下である必要があります。その他のタイプでは非空で識別可能な名前を推奨します。 null 許可: False 例: 本番コールバック取得または入力方法: 通知先一覧で検索して重複を排除したうえで入力します。 |
|
| notifyObjectUUID | string | Y | 対象通知先の UUID。 null 許可: False 例: notify_example取得または入力方法: 通知先一覧が返す content.data[].uuid から、現在のワークスペースの通知先 UUID をコピーします。 |
| openPermissionSet | boolean | カスタム操作権限を有効にするかどうか。作成時の既定は false、変更時は省略すると保持されます。作成者と Owner、および高度な設定に該当する主体は別途許可される場合があります。 null 許可: False 例: false取得または入力方法: 既定ではインターフェース権限を継承します。オブジェクトレベルの制限が必要な場合は true に設定し、permissionSet を構成します。 |
|
| optSet | json | 通知タイプに応じた完全な JSON オブジェクト。作成時は明示的に指定してください。通常タイプの変更では全体が置き換えられ、Jira/ServiceNow では同一識別のルールに従って認証情報が保持されます。 null 許可: False 例: {"url": "https://receiver.example.com/alerts"}取得または入力方法: type に応じて下表の対応する設定を選択し、受信プラットフォームまたはメンバー一覧から実際の値を取得します。 |
|
| permissionSet | array | カスタム操作可能主体の完全な配列。変更時は全体が置き換えられ、[] でクリアされます。特殊値 * は、インターフェース認証を通過したすべての識別情報がこのオブジェクトレベルのチェックを通過することを許可しますが、匿名アクセスの公開を意味しません。 null 許可: False 例: ["wsAdmin"]取得または入力方法: メンバーはワークスペースメンバー一覧のアカウント UUID、チームはメンバーグループ一覧の group_ UUID、ロールはロール一覧のロール UUID または既存のロール識別子(wsAdmin など)を使用します。表示名を入力しないでください。 |
パラメータ補足¶
Jira/ServiceNow の元のパスワード、API Key、Token、カスタムヘッダー値は返却されません。has* と credentialsRequired を使用して設定済みかどうかを判断します。その他の従来のボットおよび HTTP 設定は、元の機密値を返す場合があります。完全な返却内容を第三者に転送しないでください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/notify_object/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"notifyObjectUUID":"notify_example","name":"本番コールバック-更新"}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 保存された通知先レコード。一覧/詳細のアカウント概要や権限判定は含まれません。 |
| content.id | integer | データベース番号。以降の操作では 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/Feishu などのボットは元の署名キーを返す場合があります。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 のいずれも文字列配列を受け取り検証しますが、現在 HTTPRequest のみが実際に refMembersInfo に展開されコンテンツ解析に参加します。simpleHTTPRequest ではこの展開は行われません。 |
| content.optSet.refMembers[] | string | 関連付けられたメンバーまたはチームの UUID 文字列。 |
| content.optSet.headersConfig | object | カスタムリクエストヘッダー設定。Jira/ServiceNow の headers とは異なります。読み取りインターフェースはその機密値を復元するため、保存前に返却データを適切に扱ってください。 |
| 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": 42,
"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": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427260,
"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 を記録してください。書き込み操作の失敗後は、対象が保存済みかどうかを先に照会してから再試行してください。 |
| 404 | ft.NotFound | 変更対象が存在しない、削除済み、または現在のワークスペースにない | 業務ルートが見つかりません | 通知先一覧から有効な UUID を取得してください。 |
| 403 | ft.ForbiddenNotifyObjOperation | 対象でカスタム権限が有効になっており、現在の識別情報が操作可能範囲にない | 通知先【{}】の操作権限がありません | 管理権限を持つ識別情報が、オブジェクトの permissionSet およびワークスペースの高度な権限設定を確認してください。 |