変更¶
POST /api/v1/self_built_checker/modify
概要¶
セルフビルド検査のタイトル、関数メタ情報、および関連ポリシーを更新します。
呼び出し前の準備と使用手順¶
変更時は必ず先に get して ruleUUID を明示的に渡す必要があります。refKey を指定した場合は UUID と共に照合されます。現在の実装ではいずれの対象識別子も必須化されていないため、どちらも渡さないとワークスペースの先頭のセルフビルドルールが選択される可能性があり、対象を指定しないリクエストは送信できません。refKey のみでタイトルを変更する場合、重複名の除外条件に [None] が使用され、NOT IN(NULL) となるため、タイトルの重複を確実にチェックできません。ポリシー参照の変更やミュートタイトル/ポリシーキャッシュの更新も引き続き元の ruleUUID を使用し、照合された対象の UUID が自動的に補完されることはありません。refKey のみでは正しい参照を特定できない、または有効なソースを持たない参照が形成される可能性があります。必ず先に get で ruleUUID を取得し、特にポリシー/タイトルの変更時は明示的に渡してから変更してください。
タイトルを省略した場合は保持されます。refFuncInfo は第一階層のキー単位で更新され、args/kwargs はそれぞれ全体置換で、深いマージは行いません。{} は元のメタ情報をクリアしません。funcId は公開の変更ホワイトリストに含まれません。alertPolicyUUIDs は省略で保持、[] でクリアされます。公開 Body では callKwargs/monitorUUID/dashboardUUID/extend を宣言していないため、Front や内部パラメータを流用できません。共有タスクを更新すると、履歴の openPermissionSet=false、permissionSet=[] がリセットされるため、変更前に権限を確認してください。
保存後、ミュート範囲内のタイトルが非同期で更新され、関連するポリシーキャッシュがクリアされます。エラー時でもルールが既にコミットされている可能性があるため、まず読み戻してから再試行してください。この公開変更操作では変更監査は個別に記録されません。
本 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 パラメータメタ情報。サーバー側で統一のサブ項目 schema は定義されていないため、元の定義を保持します。 例: service取得・入力方法: 関数プラットフォームの単一パラメータメタ情報。関数定義に応じて文字列またはオブジェクトになります。 |
|
| refFuncInfo.kwargs.パラメータ名 | any | 動的なキーと値。すべての関数に共通する必須パラメータはありません。例やログに認証情報を渡さないでください。 例: production取得・入力方法: 例えば service には業務でデプロイ済みのサービス名を指定します。具体的な名前/型/取得元は関連関数のドキュメントに従います。 |
|
| alertPolicyUUIDs | array | 任意。作成時に省略または [] の場合はポリシーがバインドされません。変更時に省略した場合は保持、[] の場合はクリアされます。サーバーは現在のワークスペース内で削除されていない一致項目のみを保持し、入力がすべて有効であることは保証しません。無効化済みのポリシーも保持される場合があります。一覧で最終的な alertPolicyInfos を確認し、成功を通知の到達とみなさないでください。 null 許可: False 例: ["altpl_example"]取得・入力方法: アラートポリシー一覧から、現在のワークスペース内の削除されていないポリシー uuid を取得します。 |
|
| refFuncInfo | json | 作成時は必須、funcId も必須です。関連関数の情報を登録するのみで、本リクエストで関数を実行したり、定期スケジューリングを作成したりしません。変更時は本ページに記載されたメタ情報のサブフィールドのみを受け付け、第一階層のキー単位で更新し、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.kwargs | json | 任意の動的 JSON メタ情報。サブ値はその関数定義に従って解釈されます。本 API で使用できるトップレベルの callKwargs パラメータではなく、関数が即時に呼び出されることもありません。変更時は kwargs 全体を置換します。 null 許可: False 例: {"service": "production"}取得・入力方法: 関数のパラメータメタ情報または業務連携設定から取得します。 |
|
| refKey | string | 作成時の宣言で必須、その後は変更できません。空でなく 48 文字以下を推奨します。作成時は現在のワークスペース内の削除されていないすべての Rule の refKey と重複をチェックします(セルフビルド検査に限りません)。get では refKey のみでも可能です。modify は必ず先に get で ruleUUID を取得してから送信してください。refKey は付加的な照合条件としてのみ使用します。refKey のみではポリシー参照/キャッシュ/ミュート範囲の保守や重複名の検証を確実に行えません。 null 許可: False 例: custom-healthcheck-production取得・入力方法: 関数/業務連携用の安定した一意キーを生成します。例えば同一業務システム内の検査インスタンス識別子などです。 |
|
| ruleUUID | string | 操作対象の識別子。変更時は特にポリシー/タイトルを変更する場合、必ず先に get で明確な ruleUUID を取得する必要があります。get で同時に refKey を指定した場合は ruleUUID のみを使用し、modify で両方を指定した場合は両方の条件が一致する必要があります。関数の funcId や関連キーではありません。 null 許可: False 例: rul_self_example取得・入力方法: セルフビルド検査一覧の content.data[].uuid から、現在のワークスペースのセルフビルド検査 UUID を取得します。 |
|
| title | string | 作成時は必須、変更時は任意で省略時は保持されます。空でないタイトルは jsonScript.name にコピーされ、通常の trigger および self_built_trigger グループと名称の一意性を共有します。適切な長さを推奨します。公開宣言に上限はなく、サーバー側での生成には依存しません。関数の funcId ではありません。 null 許可: False 例: 本番サービスヘルスチェック取得・入力方法: 業務側で命名します。事前に通常のモニタリングおよびセルフビルド検査の既存名称を確認してください。 |
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/self_built_checker/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"ruleUUID":"rul_self_example","title":"本番サービスヘルスチェック(更新済み)","refFuncInfo":{"description":"検査関数の説明を更新しました。"},"alertPolicyUUIDs":["altpl_example"]}'
レスポンス¶
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 パラメータメタ情報。サーバー側で統一のサブ項目 schema は定義されていないため、元の定義を保持します。 |
| 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": 100,
"uuid": "rul_self_example",
"workspaceUUID": "wksp_example",
"monitorUUID": "",
"type": "self_built_trigger",
"refKey": "custom-healthcheck-production",
"secret": "",
"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": "wsak_example",
"createAt": 1785427200,
"updateAt": 1785427300,
"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 を提供してください。 |
| 404 | ft.MonitorNotFound | 履歴ルールに関連 monitorUUID が既に存在するが、グループが存在しないか削除済み | ルールグループが見つかりません | まず元のルールとグループを確認し、管理者が履歴の関連付けを修復してから変更してください。 |
| 404 | ft.NotFoundRuleInspector | 識別条件が現在のワークスペース内の削除されていないセルフビルド検査に一致しない | 指定されたルール/チェッカーが見つかりません | ruleUUID および任意の refKey が同一オブジェクトに属しているか確認してください。 |