作成¶
POST /api/v1/self_built_checker/create
概要¶
セルフビルトインスペクションと、それに関連付ける関数およびアラートポリシーを登録します。
呼び出し前の確認と使用手順¶
まず、関数がデプロイ済みで利用可能であることを確認し、この業務インスタンス用に安定した空でない refKey(48 文字以下を推奨)を生成し、タイトルと関数のメタ情報を漏れなく指定します。refKey がこのワークスペース内の削除されていないすべての Rule と重複すると失敗します。タイトルは通常のモニターおよびセルフビルトインスペクションと名前の重複チェックを共有します。アラートポリシーは有効な一致のみをフィルタリングします。入力した UUID が無効な場合、通知なく削除されることがあるため、リストを読み取って確認する必要があります。作成時は monitorUUID、extend、callKwargs などの内部パラメータをサポートしません。メインルールはポリシーの関連付けを追加する前に先にコミットされます。後続の処理が失敗した場合、メインルールは作成済みでもポリシーの関連付けが未完了の可能性があります。まず refKey で読み戻し、リストから alertPolicyInfos を照合してから再試行するか判断し、重複作成で refKey が衝突するのを避けてください。
この API はインスペクションのメタ情報とアラートポリシーの関連付けを登録/変更するものであり、関連関数を実行せず、1 回分のインスペクション結果も生成せず、セルフビルトインスペクション用の定期トリガータスクも作成しません。実際のスケジュールとイベント生成は業務統合/関数側が担当します。成功後はリストまたは get で設定とステータスを確認してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| alertPolicyUUIDs[*] | string | 空でない文字列を推奨。名前、通知先、または通知ポリシーの UUID ではありません。 例: altpl_example取得または入力方法: このワークスペース内の単一のアラートポリシー UUID。 |
|
| refFuncInfo.args[*] | JSON | 任意の JSON パラメータメタ情報。サーバー側は統一されたサブ項目スキーマを提供しないため、元の定義を保持します。 例: service取得または入力方法: 関数プラットフォームの単一パラメータメタ情報。関数定義に応じて文字列またはオブジェクトになります。 |
|
| refFuncInfo.kwargs.パラメータ名 | any | 動的キーと値。すべての関数に共通する必須パラメータはありません。認証情報を例/ログに渡さないでください。 例: production取得または入力方法: たとえば service には業務側でデプロイ済みのサービス名を指定します。具体的な名前/型/取得元は関連関数のドキュメントに従います。 |
|
| alertPolicyUUIDs | array | 任意。作成時に省略または [] の場合はポリシーをバインドしません。変更時に省略した場合は保持し、[] の場合はクリアします。サーバー側はこのワークスペース内の削除されていない一致項目のみを保持し、入力がすべて有効であることは保証しません。無効化されたポリシーも保持される場合があります。リストで最終的な alertPolicyInfos を照合し、成功を通知の到達とみなさないでください。 null を許可: False 例: ["altpl_example"]取得または入力方法: アラートポリシーリストから現在のワークスペースの削除されていないポリシー UUID を取得します。 |
|
| isDisabled | boolean | 作成時のみ任意指定でき、デフォルトは false です。true の場合の初期 status は 2、false の場合は 0 です。変更時はこのフィールドを受け付けず、enable/disable API を使用します。 null を許可: False 例: false取得または入力方法: 登録のみ行い有効化しない場合は true にします。 |
|
| refFuncInfo | json | Y | 作成時は必須で、funcId も必須です。関連関数の情報を登録するだけで、このリクエスト内で関数を実行したり、定期スケジュールを作成したりしません。変更時はこのページに記載されたメタ情報のサブフィールドのみを受け付け、第 1 階層のキー単位で update し、args/kwargs は全体を置換します。{} または省略時は変更しません。funcId は modify のホワイトリストにないため、変更で関数識別子を切り替えることはできません。 null を許可: False 例: {"funcId": "healthcheck.main", "description": "生产服务健康检查函数。", "definition": "main(service)", "category": "custom", "args": ["service"], "kwargs": {"service": "production"}}取得または入力方法: デプロイ済みで利用可能なカスタムインスペクション関数/関数プラットフォーム設定からメタ情報を取得します。例のリテラル値を実際の関数とみなさないでください。 |
| refFuncInfo.args | array | 任意の配列。関数プラットフォームの元のメタ情報規約に従って保存され、サーバー側はパラメータのバインドや関数シグネチャの検証を行いません。変更時は配列全体を置換します。 null を許可: False 例: ["service"]取得または入力方法: 関数のパラメータシグネチャから位置パラメータのメタ情報を取得します。 |
|
| refFuncInfo.category | string | 任意のメタ情報。固定の列挙値ではなく、Rule.type は変更しません。 null を許可: False 例: custom取得または入力方法: 関数プラットフォームの実際の分類名を取得します。 |
|
| refFuncInfo.definition | string | 任意のシグネチャ表示文字列。この API が実行するソースコードではありません。 空文字列を許可: True null を許可: False 例: main(service)取得または入力方法: 関数定義/シグネチャからエクスポートした説明を取得します。 |
|
| refFuncInfo.description | string | 任意の文字列。空にできます。変更時に明示的に空文字列を指定するとクリアされます。 空文字列を許可: True null を許可: False 例: 生产服务健康检查函数。取得または入力方法: 関数の説明ドキュメントをそのまま使用します。 |
|
| refFuncInfo.funcId | string | Y | 作成時のみ必須で、変更時は宣言しません。サーバー側の登録は、関数が実際に存在することや呼び出し可能であることを保証しません。 null を許可: False 例: healthcheck.main取得または入力方法: 実際にデプロイ済みの関数設定から完全な ID を取得します。 |
| refFuncInfo.kwargs | json | 任意の動的 JSON メタ情報。サブ値はその関数定義に従って解釈されます。この API で使用できるトップレベルの callKwargs パラメータではなく、関数を即時呼び出すこともありません。変更時は kwargs 全体を置換します。 null を許可: False 例: {"service": "production"}取得または入力方法: 関数パラメータのメタ情報または業務統合設定から取得します。 |
|
| refKey | string | Y | 作成時の宣言は必須で、その後変更できません。空でなく 48 文字以下を推奨します。作成時はセルフビルトインスペクションだけでなく、このワークスペース内の削除されていないすべての Rule の refKey と重複チェックします。get では refKey を単独で使用できます。modify ではまず get で ruleUUID を取得してから送信する必要があり、refKey は追加の照合条件としてのみ使用できます。refKey だけでは、ポリシー参照/キャッシュ/ミュート範囲と名前重複検証を確実に維持できません。 null を許可: False 例: custom-healthcheck-production取得または入力方法: 関数/業務統合用に安定した一意キーを生成します。たとえば同一業務システムの検査インスタンス識別子などです。 |
| title | string | Y | 作成時は必須、変更時は任意で、省略時は保持します。空でないタイトルは jsonScript.name にコピーされ、通常の trigger および self_built_trigger グループと名前の一意性を共有します。適切な長さを推奨します。公開宣言に上限はなく、サーバー側での生成に依存しません。関数の funcId ではありません。 null を許可: False 例: 生产服务健康检查取得または入力方法: 業務側で命名します。事前に通常のモニターおよびセルフビルトインスペクションの既存名称を確認してください。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/self_built_checker/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"refKey":"custom-healthcheck-production","title":"生产服务健康检查","refFuncInfo":{"funcId":"healthcheck.main","description":"生产服务健康检查函数。","definition":"main(service)","category":"custom","args":["service"],"kwargs":{"service":"production"}},"alertPolicyUUIDs":["altpl_example"],"isDisabled":false}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer または null | レコード番号。作成コミット前のスナップショットでは null になる場合があります。操作には uuid を使用します。 |
| content.uuid | string | rul_ ルール UUID。 |
| content.workspaceUUID | string | 所属ワークスペース。 |
| content.monitorUUID | string | 関連付けられたモニタリンググループ UUID。公開作成では宣言されず、通常は空文字列です。 |
| content.type | string | セルフビルトインスペクションでは固定で self_built_trigger です。get では型を追加限定せず、このモジュールのリスト UUID のみを使用します。 |
| content.refKey | string | 固定の業務関連キー。 |
| content.secret | string または null | 共有エンティティとの互換フィールド。セルフビルトインスペクションでは通常空です。作成スナップショットでは null になる場合があり、呼び出し認証情報としては使用しません。 |
| content.jsonScript | object | 保存されたセルフビルトインスペクション定義。Rule.type とは区別されます。 |
| content.jsonScript.type | string | 固定で selfBuiltCheck です。 |
| content.jsonScript.title | string | ルートの業務タイトル。 |
| content.jsonScript.name | string | 省略可能。作成時に title が空の場合は生成されません。空でない title は name にコピーされます。変更時に title を空にすると、履歴上の name が保持されます。 |
| content.jsonScript.refFuncInfo | object | 関連関数の情報。 |
| content.jsonScript.refFuncInfo.funcId | string | 作成時のみ必須で、変更時は宣言しません。サーバー側の登録は、関数が実際に存在することや呼び出し可能であることを保証しません。 |
| content.jsonScript.refFuncInfo.description | string | 任意の文字列。空にできます。変更時に明示的に空文字列を指定するとクリアされます。 |
| content.jsonScript.refFuncInfo.definition | string | 任意のシグネチャ表示文字列。この API が実行するソースコードではありません。 |
| content.jsonScript.refFuncInfo.category | string | 任意のメタ情報。固定の列挙値ではなく、Rule.type は変更しません。 |
| content.jsonScript.refFuncInfo.args | array | 任意の配列。関数プラットフォームの元のメタ情報規約に従って保存され、サーバー側はパラメータのバインドや関数シグネチャの検証を行いません。変更時は配列全体を置換します。 |
| content.jsonScript.refFuncInfo.kwargs | json | 任意の動的 JSON メタ情報。サブ値はその関数定義に従って解釈されます。この API で使用できるトップレベルの callKwargs パラメータではなく、関数を即時呼び出すこともありません。変更時は kwargs 全体を置換します。 |
| content.jsonScript.refFuncInfo.args[] | JSON | 任意の JSON パラメータメタ情報。サーバー側は統一されたサブ項目スキーマを提供しないため、元の定義を保持します。 |
| content.jsonScript.refFuncInfo.kwargs.パラメータ名 | any | 動的キーと値。すべての関数に共通する必須パラメータはありません。認証情報を例/ログに渡さないでください。 |
| content.jsonScript.callKwargs | object | 履歴または他の入口で保存される可能性がある実行パラメータ。公開されている create/modify では宣言されておらず、新規に返して追加することはできません。 |
| content.jsonScript.callKwargs.パラメータ名 | JSON | 具体的な実行パラメータは元の関数定義に従って解釈され、存在は保証されません。 |
| content.crontabInfo | object | セルフビルトインスペクションではこの入口から定期トリガー設定を作成しないため、通常は {} です。 |
| content.crontabInfo.歴史フィールド | JSON | 履歴レコードにスケジュール情報が保持される場合がありますが、この API で書き込み可能な設定ではありません。 |
| content.extend | object | 拡張メタ情報。公開されている Body では宣言されておらず、作成時は通常 {} です。 |
| content.extend.歴史フィールド | JSON | 履歴として保存された拡張フィールド。この入口では返して変更することはサポートされません。 |
| content.createdWay | string | 通常は manual です。履歴により import/template/空 の場合もあります。 |
| content.isLocked | integer または boolean | ロックフラグ。 |
| content.openPermissionSet | boolean | カスタム操作権限のスイッチ。作成時は false で、modify の共有タスク更新により false に戻ります。 |
| content.permissionSet | array<string> |
操作権限の主体。作成時は [] で、modify の共有更新により [] に戻ります。 |
| content.permissionSet[] | string | 履歴のアカウント/チーム/ロール識別子。 |
| 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.declaration | object | 共通宣言。 |
{
"code": 200,
"content": {
"id": null,
"uuid": "rul_self_example",
"workspaceUUID": "wksp_example",
"monitorUUID": "",
"type": "self_built_trigger",
"refKey": "custom-healthcheck-production",
"secret": null,
"jsonScript": {
"type": "selfBuiltCheck",
"title": "生产服务健康检查",
"name": "生产服务健康检查",
"refFuncInfo": {
"funcId": "healthcheck.main",
"description": "生产服务健康检查函数。",
"definition": "main(service)",
"category": "custom",
"args": [
"service"
],
"kwargs": {
"service": "production"
}
}
},
"crontabInfo": {},
"extend": {},
"createdWay": "manual",
"isLocked": 0,
"openPermissionSet": false,
"permissionSet": [],
"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 を修正します。 |
| 406 | ft.CheckObjectNameRepeat | タイトルが、このワークスペース内の削除されていない通常のモニター/セルフビルトインスペクションの名前と重複 | 検出対象のエイリアスが重複 | 名前を変更します。変更時は ruleUUID を付けて現在のオブジェクトを除外することを優先します。 |
| 500 | ft.InternalServerError | 対象未選択、フィールドの形状または長さの誤り、データベース/コミット後の非同期タスクディスパッチなどの失敗 | 内部エラー | まず現在のルールを読み戻して保存済みか確認します。このワークスペースで明確な ruleUUID を使用してから再試行し、traceId を提供します。 |
| 400 | ft.SelfBuiltCheckerRefKeyExists | このワークスペース内の削除されていないルールに同じ refKey が既に存在 | 同じ refKey を持つセルフビルトモニタリングが既に存在 | 既存のルール UUID を再利用するか、新しい安定した業務キーを生成します。 |