ISteamUGC 查询接口：筛选、分页和读取项目

ISteamUGC 查询接口适合实现 Steam 创意工坊浏览器、项目详情和管理工具。本页按创建查询、设置筛选、读取返回字段和释放资源的顺序整理接口，供需要控制返回数据的开发者查阅。

创建、发送与释放

• CreateQueryAllUGCRequest：按排序、内容类型、创建者 App ID、消费 App ID 和页码创建全局查询；页码从 1 起，每页最多 50 项。独立工具的创建者 ID 可能不同于游戏的消费 ID。
• CreateQueryUserUGCRequest：按账户 ID、用户列表类型、内容类型、排序和应用 ID 创建查询；部分投票或订阅列表仅允许当前用户访问，分页同样从 1 开始。
• CreateQueryUGCDetailsRequest：传项目 ID 数组及数量查询详情；官方当前说明最多 1000 项，界面应按实际需要缩小批量。
• SendQueryUGCRequest：传创建得到的查询句柄，返回异步调用句柄；通过 SteamUGCQueryCompleted_t 检查 m_eResult、返回数量、匹配总数及缓存状态。无效句柄返回 k_uAPICallInvalid。
• ReleaseQueryUGCRequest：使用完查询句柄后释放内存；官方描述返回 true。
• RequestUGCDetails：已弃用，应改用详情查询；旧调用返回 SteamUGCRequestUGCDetailsResult_t。

发送前设置筛选

以下方法均使用查询句柄，返回 bool，必须在发送前设置。失败可能表示句柄无效、参数为空或查询类型不支持该选项。

• AddRequiredTag 和 AddExcludedTag：传标签名以要求包含或排除，不能用于详情查询。
• AddRequiredTagGroup：传标签数组，组内至少一个匹配；多个组各须至少匹配一个，详情查询不适用。
• AddRequiredKeyValueTag：传键和值，要求项目具有该键值对。
• SetMatchAnyTag：在全部 UGC 查询中选择匹配任一必需标签还是全部。
• SetSearchText：在全部 UGC 查询中匹配标题或描述。
• SetRankedByTrendDays：为支持趋势的全部 UGC 排序设置 1 至 365 天的区间。
• SetCloudFileNameFilter：按云文件名筛选；官方正文称仅用于用户查询，但失败条件文字与之冲突，使用前应核对 SDK。
• SetAdminQuery：请求管理员查询以返回非公开项目；Steam 会检查当前用户对运行应用的权限。
• SetLanguage：设置返回标题和描述的 API 语言代码，默认 english。
• SetAllowCachedResponse：传允许缓存数据的最大年龄秒数；结果回调可识别是否使用缓存。

选择返回数据

这些 SetReturn... 方法均在发送前传句柄及选项，并返回 bool：

• SetReturnOnlyIDs 只返回 ID；SetReturnTotalOnly 只返回匹配总数，不返回实际项目；两者不适用于详情查询。
• SetReturnLongDescription 请求完整描述；未启用时返回截断至 255 字节的摘要。
• SetReturnMetadata、SetReturnChildren、SetReturnKeyValueTags、SetReturnAdditionalPreviews 分别请求元数据、子项目 ID、键值标签及额外预览。
• SetReturnPlaytimeStats 传统计天数，请求游戏时间统计。

读取成功查询的结果

以下读取函数使用成功的 SteamUGCQueryCompleted_t 查询句柄与项目索引。输出缓冲区必须按 SDK 要求提供容量，读取完后释放句柄。

• GetQueryUGCResult 填充 SteamUGCDetails_t；GetQueryUGCPreviewURL 填充主要预览图 URL；GetQueryUGCMetadata 读取元数据；这三者返回 bool。
• GetQueryUGCChildren 填充子项目 ID 数组；可先用详情中的 m_unNumChildren 分配容量。
• GetQueryUGCNumTags 返回标签数量；GetQueryUGCTag 和 GetQueryUGCTagDisplayName 按标签索引填充名称或本地化显示名，官方分别要求至少 64 和 256 字节缓冲区。
• GetQueryUGCNumKeyValueTags 返回键值标签数量；GetQueryUGCKeyValueTag 按索引输出键与值。
• GetQueryUGCNumAdditionalPreviews 返回额外预览数量；GetQueryUGCAdditionalPreview 按索引输出 URL 或视频 ID、可选原文件名及类型。
• GetQueryUGCStatistic 根据 EItemStatistic 输出统计值；GetQueryUGCContentDescriptors 填充描述词数组。官方页面的返回说明与声明存在差异，返回值语义以当前 SDK 头文件为准。
• GetNumSupportedGameVersions 返回可用项目版本数；GetSupportedGameVersionData 按版本索引输出最小、最大分支。空的一端向该端延伸，两端均空表示全部分支。

参考：ISteamUGC 官方接口。