取得¶
GET /api/v1/notify_object/get
概要¶
通知先 UUID を指定して設定とカスタム操作権限情報を読み取ります。
呼び出し前と使用手順¶
通知先一覧 から uuid を取得し、Query の notifyObjectUUID で渡します。既存のオブジェクトに対しては設定と権限の概要を返します。現在レコードが見つからない場合でも HTTP 200 のままで、content には allow_operation=null と共通宣言が含まれ、404 は返しません。対象の有無は content.uuid の存在で判断してください。updatorInfo はクエリ範囲の制限により空文字列になる場合があるため、これに基づいて未変更と判断しないでください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| notifyObjectUUID | string | Y | 必須の通知先 UUID。 例: notify_example取得または入力方法: 通知先一覧 が返す content.data[].uuid から、現在のワークスペースの通知先 UUID をコピーします。 |
パラメータ補足説明¶
allow_operation=null は、オブジェクトのカスタム操作権限が有効になっていないことを示します。API 認証が通過したことや、すべての変更権限があることの証明にはできません。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/notify_object/get' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode notifyObjectUUID=notify_example
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | オブジェクト設定と権限の概要。レコードが見つからない場合は uuid などのエンティティフィールドがありません。 |
| 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/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.creatorInfo | object または string | 作成者の概要。情報がない場合、一覧では {}、詳細では空文字列になることがあります。 |
| content.creatorInfo.uuid | string | アカウントまたは API Key の UUID。 |
| content.creatorInfo.status | integer | アカウント状態。 |
| content.creatorInfo.wsAccountStatus | integer | ワークスペース内のアカウント状態。 |
| content.creatorInfo.username | string | ユーザー名。 |
| content.creatorInfo.name | string | 表示名。 |
| content.creatorInfo.iconUrl | string | アバター URL。 |
| content.creatorInfo.email | string | メールアドレスまたは API Key の識別子。 |
| content.creatorInfo.mobile | string | 電話番号。空の場合があります。 |
| content.creatorInfo.countryCode | string | 電話番号の国番号。空の場合があります。 |
| content.creatorInfo.acntWsNickname | string | ワークスペース内のニックネーム。空の場合があります。 |
| content.updatorInfo | object または string | 更新者の概要。情報がない場合、一覧では {}、詳細では空文字列になることがあります。詳細は現在作成者のみを対象に照会するため、更新者の識別情報が異なる場合は情報がないことがあります。 |
| content.updatorInfo.uuid | string | アカウントまたは API Key の UUID。 |
| content.updatorInfo.status | integer | アカウント状態。 |
| content.updatorInfo.wsAccountStatus | integer | ワークスペース内のアカウント状態。 |
| content.updatorInfo.username | string | ユーザー名。 |
| content.updatorInfo.name | string | 表示名。 |
| content.updatorInfo.iconUrl | string | アバター URL。 |
| content.updatorInfo.email | string | メールアドレスまたは API Key の識別子。 |
| content.updatorInfo.mobile | string | 電話番号。空の場合があります。 |
| content.updatorInfo.countryCode | string | 電話番号の国番号。空の場合があります。 |
| content.updatorInfo.acntWsNickname | string | ワークスペース内のニックネーム。空の場合があります。 |
| content.allow_operation | boolean または null | カスタム操作権限の計算結果。true は許可、false は拒否。null はオブジェクトのカスタム権限が有効になっていないことを示し、API 権限を満たす必要があります。 |
| content.permissionSetInfo | object | permissionSet の識別子をキーとするプリンシパル概要。permissionSet が空でない場合にのみ表示されます。 |
| content.permissionSetInfo.プリンシパル識別子 | object | メンバーの場合はアカウント概要、チーム/ロールの場合は {name,status}、無効なプリンシパルは空オブジェクトになる場合があります。 |
| content.permissionSetInfo.プリンシパル識別子.name | string | チームまたはロールの表示名。メンバーのフィールドは creatorInfo と一致します。 |
| content.permissionSetInfo.プリンシパル識別子.status | integer | プリンシパル状態。0 は正常。 |
| content.permissionSetInfo.プリンシパル識別子.uuid | string | アカウントまたは API Key の UUID。 |
| content.permissionSetInfo.プリンシパル識別子.wsAccountStatus | integer | ワークスペース内のアカウント状態。 |
| content.permissionSetInfo.プリンシパル識別子.username | string | ユーザー名。 |
| content.permissionSetInfo.プリンシパル識別子.iconUrl | string | アバター URL。 |
| content.permissionSetInfo.プリンシパル識別子.email | string | メールアドレスまたは API Key の識別子。 |
| content.permissionSetInfo.プリンシパル識別子.mobile | string | 電話番号。空の場合があります。 |
| content.permissionSetInfo.プリンシパル識別子.countryCode | string | 電話番号の国番号。空の場合があります。 |
| content.permissionSetInfo.プリンシパル識別子.acntWsNickname | string | ワークスペース内のニックネーム。空の場合があります。 |
| 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": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"creatorInfo": "",
"updatorInfo": "",
"allow_operation": null,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
対象が見つからない場合
{
"code": 200,
"content": {
"allow_operation": null,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 宣言されていない Query パラメータを使用した場合、またはパラメータがルールに違反した場合 | パラメータ解析失敗 | Query パラメータ表と例を確認してください。 |
| 500 | ft.InternalServerError | 設定の読み取り、復号、またはデータベースクエリに失敗した場合 | 内部エラー | traceId とオブジェクト UUID を保持してサポートに連絡してください。読み取れない資格情報設定を繰り返しコピーしないでください。 |