Module: JPSClient::API::Tag

Included in:
Client
Defined in:
lib/jpsclient/api/tag.rb

Overview

Tag 相关 API 处理标签管理相关接口

Instance Method Summary collapse

Instance Method Details

#batch_create_tags(tags: []) ⇒ Array<Hash>

便捷方法：批量创建标签注意：此方法会逐个调用 API，返回结果数组

Parameters:

  • tags (Array<Hash>) (defaults to: []) —

    标签数组

Returns:

  • (Array<Hash>) —

    每个请求的响应结果



145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/jpsclient/api/tag.rb', line 145

def batch_create_tags(tags: [])
  return [] if tags.empty?

  results = []
  tags.each do |tag_params|
    result = create_tag(params: tag_params)
    results << result
  end

  results
end

#batch_update_weights(tag_weights: {}, type:) ⇒ Hash

批量更新标签权重（便捷方法）

Parameters:

  • tag_weights (Hash) (defaults to: {}) —

    标签ID到权重的映射例如: { “1” => 100, “2” => 90, “3” => 80 }

  • type (String) —

    标签类型

Returns:

  • (Hash) —

    API响应



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/jpsclient/api/tag.rb', line 227

def batch_update_weights(tag_weights: {}, type:)
  return update_tag_weights(weights: []) if tag_weights.empty?

  # 先获取所有标签信息
  response = get_tags(params: { type: type })

  # 如果获取标签失败，直接返回错误响应
  return response unless response && response['data']

  tags = response['data']['tags'] || response['data'][:tags] || []
  weights_array = []

  tag_weights.each do |tag_id, weight|
    tag = tags.find { |t| (t['id'] || t[:id]).to_s == tag_id.to_s }
    if tag
      weights_array << {
        id: tag['id'] || tag[:id],
        weight: weight,
        name: tag['name'] || tag[:name],
        type: tag['type'] || tag[:type],
        color: tag['color'] || tag[:color],
        description: tag['description'] || tag[:description]
      }
    end
  end

  # 如果没有找到任何有效标签，返回空权重数组的更新（将由API处理错误）
  update_tag_weights(weights: weights_array)
end

#copy_tag(tagId:, new_name:, tag_type: nil) ⇒ Hash

复制标签注意：此功能需要先获取标签详情，然后创建新标签

Parameters:

  • tagId (String, Integer) —

    源标签ID

  • new_name (String) —

    新标签名称

  • tag_type (String) (defaults to: nil) —

    标签类型（如果能提供）

Returns:

  • (Hash) —

    API响应

Raises:



264
265
266
267
268
 
# File 'lib/jpsclient/api/tag.rb', line 264

def copy_tag(tagId:, new_name:, tag_type: nil)
  # 由于没有获取单个标签详情的API，此方法暂时无法实现
  # 建议使用 get_tags 获取标签列表后在客户端查找并复制
  raise JPSClient::ExceptionError, "Copy tag feature requires get_tag_detail API which is not available"
end

#create_tag(params: {}) ⇒ Hash

创建标签

Parameters:

  • params (Hash) (defaults to: {}) —

    标签信息参数

    • name: 标签名称（必需）

    • type: 标签类型（必需）

    • color: 标签颜色（可选）

    • description: 标签描述（可选）

Returns:

  • (Hash) —

    API响应

Raises:



15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/jpsclient/api/tag.rb', line 15

def create_tag(params: {})
  config = @request_config && @request_config["tag_create"]
  raise JPSClient::ExceptionError, "Missing config for tag_create" unless config && config["url"]

  # 参数验证
  required_fields = [:name, :type]
  missing_fields = required_fields.select { |field| params[field].nil? || params[field].to_s.empty? }

  if missing_fields.any?
    raise JPSClient::ExceptionError, "Missing required fields: #{missing_fields.join(', ')}"
  end

  path = config["url"]

  return request_with_auth(:post, path, body: params)
end

#delete_tag(tagId:) ⇒ Hash

删除标签

Parameters:

  • tagId (String, Integer) —

    标签ID（必需）

Returns:

  • (Hash) —

    API响应

Raises:



62
63
64
65
66
67
68
69
 
# File 'lib/jpsclient/api/tag.rb', line 62

def delete_tag(tagId:)
  config = @request_config && @request_config["tag_delete"]
  raise JPSClient::ExceptionError, "Missing config for tag_delete" unless config && config["url"]

  path = config["url"].gsub("{tagId}", tagId.to_s)

  return request_with_auth(:delete, path)
end

#get_tag_applications(tagId:) ⇒ Array

便捷方法：获取标签的应用列表

Parameters:

  • tagId (String, Integer) —

    标签ID

Returns:

  • (Array) —

    应用列表



199
200
201
202
203
204
205
206
 
# File 'lib/jpsclient/api/tag.rb', line 199

def get_tag_applications(tagId:)
  response = get_tag_resources(tagId: tagId)

  # 如果请求失败，返回空数组
  return [] unless response && response['data']

  response['data']['applications'] || response['data'][:applications] || []
end

#get_tag_ideas(tagId:) ⇒ Array

便捷方法：获取标签的创意列表

Parameters:

  • tagId (String, Integer) —

    标签ID

Returns:

  • (Array) —

    创意列表



212
213
214
215
216
217
218
219
 
# File 'lib/jpsclient/api/tag.rb', line 212

def get_tag_ideas(tagId:)
  response = get_tag_resources(tagId: tagId)

  # 如果请求失败，返回空数组
  return [] unless response && response['data']

  response['data']['ideas'] || response['data'][:ideas] || []
end

#get_tag_resources(tagId:) ⇒ Hash

获取标签关联的资源

Parameters:

  • tagId (String, Integer) —

    标签ID（必需）

Returns:

  • (Hash) —

    API响应，包含applications和ideas数组

Raises:



120
121
122
123
124
125
126
127
 
# File 'lib/jpsclient/api/tag.rb', line 120

def get_tag_resources(tagId:)
  config = @request_config && @request_config["tag_resources"]
  raise JPSClient::ExceptionError, "Missing config for tag_resources" unless config && config["url"]

  path = config["url"].gsub("{tagId}", tagId.to_s)

  return request_with_auth(:get, path)
end

#get_tags(params: {}) ⇒ Hash

获取标签列表

Parameters:

  • params (Hash) (defaults to: {}) —

    查询参数

    • page: 页码（可选）

    • type: 标签类型（必需）

Returns:

  • (Hash) —

    API响应

Raises:



102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/jpsclient/api/tag.rb', line 102

def get_tags(params: {})
  config = @request_config && @request_config["tag_list"]
  raise JPSClient::ExceptionError, "Missing config for tag_list" unless config && config["url"]

  # type 参数是必需的
  unless params[:type] || params["type"]
    raise JPSClient::ExceptionError, "Missing required parameter: type"
  end

  path = config["url"]

  return request_with_auth(:get, path, params: params)
end

#get_tags_by_color(type:, color:) ⇒ Array<Hash>

便捷方法：按颜色筛选标签获取指定类型的标签，然后在客户端筛选颜色

Parameters:

  • type (String) —

    标签类型（必需）

  • color (String) —

    标签颜色

Returns:

  • (Array<Hash>) —

    符合条件的标签数组



163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/jpsclient/api/tag.rb', line 163

def get_tags_by_color(type:, color:)
  response = get_tags(params: { type: type })

  # 如果请求失败，返回空数组
  return [] unless response && response['data']

  tags = response['data']['tags'] || response['data'][:tags] || []
  tags.select { |tag|
    (tag['color'] || tag[:color]) == color
  }
end

#get_tags_by_type(type:, page: nil) ⇒ Hash

便捷方法：按类型获取标签

Parameters:

  • type (String) —

    标签类型

  • page (Integer) (defaults to: nil) —

    页码（可选）

Returns:

  • (Hash) —

    API响应



134
135
136
137
138
 
# File 'lib/jpsclient/api/tag.rb', line 134

def get_tags_by_type(type:, page: nil)
  params = { type: type }
  params[:page] = page if page
  get_tags(params: params)
end

#get_tags_statistics(type:) ⇒ Hash

标签统计信息获取标签并计算统计数据

Parameters:

  • type (String) —

    标签类型

Returns:

  • (Hash) —

    包含统计数据的哈希



275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/jpsclient/api/tag.rb', line 275

def get_tags_statistics(type:)
  response = get_tags(params: { type: type })

  # 如果请求失败，返回空统计
  unless response && response['data']
    return {
      total_count: 0,
      tags_with_resources: 0,
      empty_tags: 0,
      color_distribution: {},
      top_used: []
    }
  end

  tags = response['data']['tags'] || response['data'][:tags] || []

  {
    total_count: tags.size,
    tags_with_resources: tags.count { |t|
      (t['relatedCount'] || t[:relatedCount] || 0) > 0
    },
    empty_tags: tags.count { |t|
      (t['relatedCount'] || t[:relatedCount] || 0) == 0
    },
    color_distribution: tags.group_by { |t|
      t['color'] || t[:color] || "no_color"
    }.transform_values(&:size),
    top_used: tags.sort_by { |t|
      -(t['relatedCount'] || t[:relatedCount] || 0)
    }.first(10)
  }
end

#search_tags(type:, keyword:) ⇒ Array<Hash>

便捷方法：搜索标签获取指定类型的标签，然后在客户端搜索

Parameters:

  • type (String) —

    标签类型（必需）

  • keyword (String) —

    搜索关键词

Returns:

  • (Array<Hash>) —

    符合搜索条件的标签数组



181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/jpsclient/api/tag.rb', line 181

def search_tags(type:, keyword:)
  response = get_tags(params: { type: type })

  # 如果请求失败，返回空数组
  return [] unless response && response['data']

  tags = response['data']['tags'] || response['data'][:tags] || []
  tags.select { |tag|
    name = (tag['name'] || tag[:name] || "").to_s
    description = (tag['description'] || tag[:description] || "").to_s
    name.include?(keyword) || description.include?(keyword)
  }
end

#update_tag(params: {}) ⇒ Hash

更新标签

Parameters:

  • params (Hash) (defaults to: {}) —

    更新参数

    • tagId: 标签ID（必需）

    • name: 标签名称（必需）

    • type: 标签类型（必需）

    • color: 标签颜色（可选）

    • description: 标签描述（可选）

Returns:

  • (Hash) —

    API响应

Raises:



41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/jpsclient/api/tag.rb', line 41

def update_tag(params: {})
  config = @request_config && @request_config["tag_update"]
  raise JPSClient::ExceptionError, "Missing config for tag_update" unless config && config["url"]

  # 参数验证
  required_fields = [:tagId, :name, :type]
  missing_fields = required_fields.select { |field| params[field].nil? || params[field].to_s.empty? }

  if missing_fields.any?
    raise JPSClient::ExceptionError, "Missing required fields: #{missing_fields.join(', ')}"
  end

  path = config["url"]

  return request_with_auth(:put, path, body: params)
end

#update_tag_weights(weights: []) ⇒ Hash

更新标签权重

Parameters:

  • weights (Array<Hash>) (defaults to: []) —

    权重数组每个项包含：

    • id: 标签ID

    • weight: 权重值

    • name: 标签名称

    • type: 标签类型

    • color: 标签颜色（可选）

    • description: 标签描述（可选）

Returns:

  • (Hash) —

    API响应

Raises:



82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/jpsclient/api/tag.rb', line 82

def update_tag_weights(weights: [])
  config = @request_config && @request_config["tag_weights"]
  raise JPSClient::ExceptionError, "Missing config for tag_weights" unless config && config["url"]

  if weights.empty?
    raise JPSClient::ExceptionError, "Weights array cannot be empty"
  end

  path = config["url"]
  params = { weights: weights }

  return request_with_auth(:post, path, body: params)
end