変更¶
POST /api/v1/tag/{tag_uuid}/modify
概要¶
タグを部分的に変更し、新しいスコープに基づいて適用されなくなった参照をクリーンアップします。
呼び出し前の準備と使用手順¶
部分更新では、送信されていないフィールドは保持され、空文字列は明示的な上書きとして扱われます。完全に同一のリクエストは元のエンティティを返し、変更監査は記録されません。scope が変更されると、許可されなくなったリソース参照と、モニターの extend.incidentsTags 内の該当タグ名がクリーンアップされます。名前/色の変更によって、文字列でバインドされているすべての外部データが自動的に変更されるわけではありません。
現在の OpenAPI modify はプレビューを必須とせず、scopePreviewToken を省略すると直接クリーンアップを実行できます。影響を確認するには、まず scope_preview で確認し、その後、同じ呼び出し元、同じ scope、および返された token で送信することを推奨します。token を渡すと 600 秒の有効期間と完全な影響フィンガープリントが検証され、リソース関係/設定が変更された場合は再プレビューが必要です。設定変更のない空操作では token を検証しません。スコープ、名前の検証、参照のクリーンアップは同じトランザクションで実行され、失敗するとロールバックされます。送信後に Synthetic テスト設定の同期が失敗した場合は pendingDialingTaskUUIDs に表示されます。タグはすでに変更されているため、変更全体のロールバックとして扱わないでください。
ルートパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| tag_uuid | string | Y | このワークスペースのタグ UUID。タグ名、一覧の数値ページ番号、リソース UUID ではありません。 例: tag_example取得/入力方法: タグ一覧 の content.data[].uuid から取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得/入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| scope[*] | string | 配列の要素。all と具体値を混在させないでください。 例: monitor取得/入力方法: 上位の列挙値から単一のスコープを選択します。 |
|
| colour | string | 任意の文字列。作成時のデフォルトは default。変更時に省略した場合は保持し、空文字列は新しい値として保存します。最大 50 で、カウント単位は前述と同じです。サーバー側で色の列挙値は固定されていないため、顧客向け UI がサポートする色表現を選択する必要があります。 null 許容: False 最大長: 50 例: default取得/入力方法: 一覧にある既存の colour またはデフォルトの default を使用できます。 |
|
| description | string | 任意。作成時に省略した場合は空文字列、変更時に省略した場合は保持、明示的な空文字列はクリアします。最大 100 で、カウント単位は前述と同じです。 null 許容: False 最大長: 100 例: 生产资源统一标记。取得/入力方法: 業務担当者がこのタグの用途を説明します。 |
|
| name | string | 作成時は必須、変更時は任意。空でないことを推奨。最大 50 カウント単位(ASCII/半角カタカナは 1、その他の文字は 2)。名前は大文字と小文字を区別して、削除されていない重複を判定します。表示名を UUID として扱いません。コロンを含む既存タグを許可します。この公開一覧では Front の通常/KV の振り分けを行いません。 null 許容: False 最大長: 50 例: production取得/入力方法: 業務で定義したタグ名。タグ一覧 で既存の使用名を先に確認します。 |
|
| scope | any | 空でないスコープ配列。列挙値は all(グローバル)、scene(シーン)、monitor(モニター)、dialing(Synthetic テスト)、security(セキュリティ)、infrastructure(インフラストラクチャ)、catalog(統合カタログ)です。旧形式の単一値文字列と互換性があります。all は他の値と混在できません。重複値は除去され、固定の列挙順で返されます。[]、null、未知の値は受け付けません。新規作成/インポート時に省略した場合のデフォルトは ["all"]、変更時に省略した場合は以前の値を保持します。scope はタグの適用範囲のみを制限し、リソース権限を付与しません。インフラストラクチャ/統合カタログの名前バインディングは、ここでのエンティティ参照のクリーンアップによって書き換えられません。 null 許容: False 例: ["scene", "monitor"]取得/入力方法: タグをバインドするリソースのビジネスタイプに応じて選択します。 |
|
| scopePreviewToken | string | 任意。実際に scope を変更する場合にのみ検証に使用されます。最大 128。有効期間は 600 秒で、呼び出し元/ワークスペース/タグ/新しいスコープおよび現在の影響範囲にバインドされます。変更または期限切れの場合は再プレビューが必要です。現在の公開 modify では、省略すると直接クリーンアップして変更でき、事前確認は必須ではありません。指定した場合は有効性を検証し、古い token で再試行しないでください。 null 許容: False 例: PREVIEW-TOKEN取得/入力方法: このタグのスコーププレビュー の content.previewToken から取得します。 |
パラメータ補足説明¶
データ説明
- リクエストパラメータ説明
| パラメータ名 | type | 説明 |
|---|---|---|
| name | string | タグ名 |
| description | string | フィールドの説明情報 |
| color | string | フロントエンドとバックエンドで取り決めた色タイプ。default、style_key1、style_key2 ~~ |
- 色の color フィールドのタイプ別色対応:
{ "default": {"background": "#CCE6FF", "color": "rgba(0,0,0,0.8)"}, "style_key1": {"background": "#3333FE", "color": "#FFFFFF"}, "style_key2": {"background": "#428BCA", "color": "#FFFFFF"}, "style_key3": {"background": "#364450", "color": "#FFFFFF"}, "style_key4": {"background": "#E0E1FF", "color": "rgba(0,0,0,0.8)"}, "style_key5": {"background": "#9400D3", "color": "#FFFFFF"}, "style_key6": {"background": "#EDDBFF", "color": "rgba(0,0,0,0.8)"}, "style_key7": {"background": "#CC328B", "color": "#FFF"}, "style_key8": {"background": "#FCDEF0", "color": "rgba(0,0,0,0.8)"}, "style_key9": {"background": "#DC143D", "color": "#FFFFFF"}, "style_key10": {"background": "#FCBABA", "color": "rgba(0,0,0,0.8)"}, "style_key11": {"background": "#BD0B48", "color": "#FFFFFF"}, "style_key12": {"background": "#FDECD2", "color": "rgba(0,0,0,0.8)"}, "style_key13": {"background": "#FFC29C", "color": "rgba(0,0,0,0.8)"}, "style_key14": {"background": "#ED9120", "color": "#FFFFFF"}, "style_key15": {"background": "#CD5B44", "color": "#FFFFFF"}, "style_key16": {"background": "#FAF570", "color": "rgba(0,0,0,0.8)"}, "style_key17": {"background": "#C29953", "color": "#FFFFFF"}, "style_key18": {"background": "#02B140", "color": "#FFFFFF"}, "style_key19": {"background": "#D5F4D5", "color": "rgba(0,0,0,0.8)"}, "style_key20": {"background": "#009966", "color": "#FFFFFF"}, "style_key21": {"background": "#023220", "color": "#FFFFFF"}, "style_key22": {"background": "#E7E7E7", "color": "rgba(0,0,0,0.8)"}, "style_key23": {"background": "#808080", "color": "#FFFFFF"} }
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/tag/tag_example/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"description":"生产资源标记已更新。"}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.id | integer | エンティティレコード番号。一覧の id は UUID 文字列です。一覧のフィールドを参照してください。 |
| content.uuid | string | tag_タグ UUID。 |
| content.workspaceUUID | string | 所属ワークスペース。 |
| content.name | string | タグ名。 |
| content.description | string | 用途説明。 |
| content.colour | string | 色表現。 |
| content.scope | array<string> |
正規化されたスコープ。履歴上の null/空の scope は ["all"] として返されます。 |
| content.scope[] | string | all/scene/monitor/dialing/security/infrastructure/catalog のいずれか。 |
| content.status | integer | 0 は有効、3 は削除済み。その他の履歴状態は実際のデータに基づきます。 |
| content.creator | string | 作成者。 |
| content.updator | string | 最終更新者。 |
| content.createAt | integer | 作成日時(Unix 秒)。 |
| content.updateAt | integer | 更新日時(Unix 秒)。未更新の場合は -1。 |
| content.deleteAt | integer | 削除日時(Unix 秒)。未削除の場合は -1。 |
| content.affectedRelationCount | integer | 実際に scope を変更したときにクリーンアップされたエンティティ参照数。省略可能。 |
| content.affectedConfigCount | integer | 実際に scope を変更したときに incidentsTags のモニタールール設定からクリーンアップされた件数。省略可能。 |
| content.pendingDialingTaskUUIDs | array<string> |
タグは送信済みだが Synthetic テスト設定の更新に失敗したタスク UUID。省略可能。 |
| content.pendingDialingTaskUUIDs[] | string | 管理者が確認し、再送信する必要があるタスク UUID。 |
| content.declaration | object | 共通宣言。 |
{
"code": 200,
"content": {
"id": 100,
"uuid": "tag_example",
"workspaceUUID": "wksp_example",
"name": "production",
"description": "生产资源标记已更新。",
"colour": "default",
"scope": [
"scene",
"monitor"
],
"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.TagNameExists | このワークスペースに同名の削除されていないタグが存在します | 同名のタグがすでに存在します | 名前を変更するか、先に元のタグを確認してください。 |
| 500 | ft.InternalServerError | データベース、タグ/権限構造、キャッシュ、またはレスポンスのフォーマット処理に失敗しました | 内部エラー | リクエストを確認したうえでタグの現在の状態を読み戻してください。書き込みはすでにコミットされている可能性があるため、むやみに繰り返さず、失敗が続く場合は traceId を提供してください。 |
| 404 | ft.ObjectNotExists | このワークスペースに対応する有効なタグがない、または削除済みです | 指定されたオブジェクトが存在しません | 現在のワークスペース一覧から有効な UUID を取得してください。 |
| 400 | ft.TagScopeConfirmationRequired | scope 変更時に空/欠落した資格情報が渡され、そのパスで確認が必要です。たとえば、明示的な空 token は確認チェックをトリガーします | 影響を受けるリソースを先に確認してください | 先にプレビューし、返された token で送信してください。この公開エントリポイントでは token を完全に省略すると直接変更できるため、影響は自身で確認してください。 |
| 400 | ft.TagScopePreviewExpired | scope が実際に変更され、渡された token が期限切れ、または呼び出し元/範囲/現在の影響フィンガープリントと一致しません | 影響範囲が変更されました。再プレビューして確認してください | 同じ scope を再プレビューし、新しい token で再送信してください。 |