コンテンツにスキップ

作成



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 を提供してください。

フィードバック

このページは役に立ちましたか?