作成¶
POST /api/v1/tag/create
概要¶
ビジネスタグとその適用範囲を作成します。
呼び出し前の確認と使用手順¶
対象のワークスペースで名前が既に使用されていないことを確認してから、スコープが明確なタグを作成します。名前は大文字と小文字を区別します。サーバー側の文字列宣言では非空チェックが保証されないため、呼び出し元は空でないビジネス名を指定してください。デフォルトは scope=["all"]、colour=default、description は空文字列です。タグを作成しても、どのリソースにも自動でタグが付与されず、リソース権限も付与されません。対応するリソースの API でタグ名/UUID を使用してバインドします。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| scope[*] | string | 配列の要素です。all と具体的な値を混在させないでください。 例: monitor取得または入力方法: 上位の列挙値から単一のスコープを選択します。 |
|
| colour | string | 任意の文字列です。作成時はデフォルトで default になります。変更時に省略した場合は保持され、空文字列は新しい値として保存されます。最大 50(上記と同じカウント単位)。サーバー側で色の列挙値は固定されていないため、顧客インターフェースでサポートされる色表現を選択する必要があります。 null を許可: False 最大長: 50 例: default取得または入力方法: 一覧にある既存の colour またはデフォルトの default を使用できます。 |
|
| description | string | 任意です。作成時に省略した場合は空文字列になります。変更時に省略した場合は保持され、明示的な空文字列はクリアされます。最大 100(上記と同じカウント単位)。 null を許可: False 最大長: 100 例: 生产资源统一标记。取得または入力方法: ビジネス側がこのタグの用途を説明します。 |
|
| name | string | Y | 作成時は必須、変更時は任意です。空でないことを推奨します。最大 50 カウント単位(ASCII/半角カタカナは 1、その他の文字は 2)。名前は大文字と小文字を区別して、削除されていない重複を判定します。表示名を UUID として扱いません。コロンを含む既存のタグは許可されますが、この公開リストではフロントエンドの通常/KV の振り分けは行いません。 null を許可: False 最大長: 50 例: production取得または入力方法: ビジネス側でカスタマイズしたタグ名。まずタグ一覧で使用済みの名前を確認してください。 |
| scope | any | 空でないスコープ配列です。列挙値は all(グローバル)、scene(シーン)、monitor(モニタリング)、dialing(Synthetic テスト)、security(セキュリティ)、infrastructure(インフラストラクチャ)、catalog(統合カタログ)です。旧形式の単一値文字列とも互換性があります。all は他の値と混在できません。重複値は重複排除され、固定の列挙順序で返されます。[]/null/未知の値は受け付けません。新規作成/インポート時に省略した場合はデフォルトの ["all"]、変更時に省略した場合は以前の値を保持します。scope はタグの適用範囲のみを制限し、リソース権限を付与しません。インフラストラクチャ/統合カタログの名前バインディングは、ここでのエンティティ参照のクリーンアップによって書き換えられません。 null を許可: False 例: ["scene", "monitor"]取得または入力方法: タグをバインドする必要があるリソースのビジネスタイプに応じて選択します。 |
パラメータ補足説明¶
データ説明
- リクエストパラメータ説明
| パラメータ名 | 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/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"name":"production","description":"生产资源统一标记。","colour":"default","scope":["scene","monitor"]}'
応答¶
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.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": "",
"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.TagNameExists | このワークスペースに同名の削除されていないタグが存在します | 同名のタグが既に存在します | 名前を変更するか、先に元のタグを確認してください。 |
| 500 | ft.InternalServerError | データベース、タグ/権限構造、キャッシュ、または応答フォーマットに失敗しました | 内部エラー | リクエストを確認した後にタグの現在の状態を読み戻してください。書き込みが既にコミットされている可能性があるため、むやみに繰り返さないでください。失敗が続く場合は traceId を提供してください。 |